Creare e gestire i posizionamenti dei dati

Nota: questa funzionalità è disponibile con la versione Enterprise Plus di Spanner. Per ulteriori informazioni, consulta la panoramica delle versioni di Spanner.

Questa pagina descrive come creare e gestire i posizionamenti dei dati in Spanner.

Per ulteriori informazioni sul funzionamento del partizionamento geografico, consulta la panoramica del partizionamento geografico.

Gestire i metadati di routing

Quando l'applicazione deve leggere o scrivere dati, Spanner utilizza i metadati di routing per trovare i server che contengono le righe specifiche necessarie.

La scelta della posizione dei metadati di routing dipende dal fatto che la maggior parte delle richieste client riguardi dati all'interno o all'esterno della regione e se utilizzi una configurazione con più regioni. Le impostazioni dei metadati di routing influiscono sulla latenza e non possono essere modificate dopo la creazione dei posizionamenti.

L'opzione per_placement_routing_metadata determina la posizione dei metadati di routing in base alle seguenti impostazioni:

• TRUE: se impostata su TRUE, i metadati di routing risiedono nella stessa partizione dell'istanza dei dati. I metadati di routing sono partizionati per regione. In questo modo si riduce la latenza per le richieste di dati nella regione (ovvero il client e i dati utente richiesti si trovano nella stessa regione), in modo che Spanner non debba effettuare chiamate fuori regione per i metadati di routing. Tuttavia, questa impostazione potrebbe aumentare la latenza per le richieste fuori regione, per le ricerche negative in cui non esistono righe di posizionamento e per le query che richiedono un indice globale.

  Ti consigliamo di utilizzare questa impostazione se prevedi che la maggior parte delle richieste riguardi i dati utente nella stessa regione del client e se la partizione predefinita non dispone di regioni di lettura/scrittura o di sola lettura in co-location con tutte le partizioni dell'istanza.

• FALSE: i metadati di routing sono centralizzati nella partizione predefinita.

  Ti consigliamo di utilizzare questa impostazione se prevedi che i client cerchino spesso dati fuori regione, ad esempio un client nella regione UE che cerca dati per utenti negli Stati Uniti.

  Valuta questa impostazione anche se la partizione dell'istanza predefinita utilizza una configurazione con più regioni che fornisce regioni di lettura/scrittura o di sola lettura in co-location con tutte le partizioni dell'istanza. Con questa impostazione, una replica dei metadati di routing completi viene archiviata con ogni replica della partizione dell'istanza predefinita. Di conseguenza, tutte le regioni con partizioni dell'istanza hanno una replica dei metadati di routing. In questo modo, sia le richieste nella regione sia quelle fuori regione possono cercare i metadati di routing localmente.

Nota: prima di luglio 2026, il valore predefinito era FALSE. A partire da luglio 2026, il valore predefinito è TRUE. Potresti notare risultati di latenza diversi tra i database creati prima e dopo la modifica del valore predefinito. Ti consigliamo di impostare questa opzione in modo esplicito per evitare modifiche impreviste.

Impostare l'opzione per_placement_routing_metadata

Nota: l'impostazione di questa opzione non riesce se esistono già posizionamenti dei dati.

Per impostare per_placement_routing_metadata nella Google Cloud console, aggiorna questa opzione nello schema del database. Per informazioni su come aggiornare uno schema, consulta la pagina Apportare aggiornamenti dello schema.

L'opzione per_placement_routing_metadata accetta valori booleani. Se questa opzione è TRUE, i metadati di routing risiedono nella stessa partizione dell'istanza dei dati. Se FALSE, i metadati di routing risiedono nella partizione dell'istanza predefinita.

L'esempio seguente mostra un comando ALTER DATABASE di GoogleSQL per impostare questa opzione:

ALTER DATABASE DATABASE_NAME SET OPTIONS ( per_placement_routing_metadata = METADATA_BOOLEAN)

Sostituisci quanto segue:

• DATABASE_NAME: il nome del database.
• METADATA_BOOLEAN: il valore di per_placement_routing_metadata. Se TRUE, i metadati di routing risiedono nella stessa partizione dell'istanza dei dati. Se FALSE, i metadati di routing risiedono nella partizione dell'istanza predefinita.

Creare un posizionamento dei dati

Dopo aver creato le partanner partizioni e i database e aver impostato l'opzione per_placement_routing_metadata, crea il posizionamento.

Console

1. Vai alla pagina Istanze nella Google Cloud console.

   Istanze

2. Seleziona l'istanza con le partizioni dell'istanza create dall'utente.

3. Seleziona il database di cui vuoi partizionare i dati.

4. Nel menu di navigazione, fai clic su Spanner Studio.

5. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

6. Inserisci l'istruzione CREATE PLACEMENT (GoogleSQL, PostgreSQL) DDL.

   Ad esempio, puoi eseguire il seguente comando per creare una tabella di posizionamento europeplacement nella partizione dell'istanza europe-partition:

   GoogleSQL

   CREATE PLACEMENT europeplacement OPTIONS (instance_partition="europe-partition");
   

   PostgreSQL

   CREATE PLACEMENT europeplacement WITH (instance_partition='europe-partition');
   

   (Facoltativo) Puoi anche utilizzare il riquadro Esplora oggetti per visualizzare, cercare e interagire con gli oggetti di posizionamento. Per ulteriori informazioni, consulta la pagina Esplorare i dati.

7. Fai clic su Esegui.

gcloud

Per creare un posizionamento con il comando Google Cloud CLI, utilizza gcloud spanner databases ddl update.

Ad esempio, crea un posizionamento nella partizione dell'istanza europe-partition:

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT europeplacement OPTIONS (instance_partition='europe-partition')"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT europeplacement WITH (instance_partition='europe-partition')"

Impostare il leader predefinito per un posizionamento

Puoi impostare la regione leader predefinita di un posizionamento se la sua località si trova in una configurazione con più regioni. La nuova regione leader deve essere una delle due regioni di lettura/scrittura all'interno della località di posizionamento con più regioni. Per ulteriori informazioni, tabelle delle configurazioni disponibili con più regioni.

Se non imposti una regione leader, il posizionamento utilizza la regione leader predefinita specificata dalla sua località. Per un elenco delle regione leader per ogni località con più regioni, consulta le tabelle delle configurazioni disponibili con più regioni. La regione leader predefinita è indicata con una L. Ad esempio, la regione leader predefinita di nam8 si trova a Los Angeles(us-west2). Le seguenti istruzioni spiegano come impostarla su Oregon(us-west1).

Console

1. Vai alla pagina Istanze nella Google Cloud console.

   Istanze

2. Seleziona l'istanza con le partizioni dell'istanza create dall'utente.

3. Seleziona il database di cui vuoi partizionare i dati.

4. Nel menu di navigazione, fai clic su Spanner Studio.

5. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

6. Inserisci l'istruzione CREATE PLACEMENT (GoogleSQL, PostgreSQL) DDL.

   Ad esempio, puoi eseguire il seguente comando per creare una tabella di posizionamento nam8placement nella partizione dell'istanza nam8-partition con la località leader predefinita impostata su us-west1:

   GoogleSQL

   CREATE PLACEMENT `nam8placement`
     OPTIONS (instance_partition="nam8-partition", default_leader="us-west1");
   

   PostgreSQL

   CREATE PLACEMENT nam8placement WITH (instance_partition='nam8-partition', default_leader='us-west1');
   

   (Facoltativo) Puoi anche utilizzare il riquadro Esplora oggetti per visualizzare, cercare e interagire con gli oggetti di posizionamento. Per ulteriori informazioni, consulta la pagina Esplorare i dati.

7. Fai clic su Esegui.

gcloud

Per creare un posizionamento con il comando gcloud CLI, utilizza gcloud spanner databases ddl update.

Ad esempio, crea una tabella di posizionamento nam8placement nella partizione dell'istanza nam8-partition con la località leader predefinita impostata su us-west1:

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT nam8placement \
     OPTIONS (instance_partition='nam8-partition', default_leader='us-west1')"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT nam8placement WITH (instance_partition='nam8-partition', default_leader='us-west1')"

Eliminare un posizionamento dei dati

Prima di eliminare un posizionamento, devi rimuovere tutti i dati delle righe dal posizionamento. Una volta fatto, puoi utilizzare la Google Cloud console o gcloud CLI per eliminare il posizionamento.

Console

1. Nel menu di navigazione, fai clic su Spanner Studio.
2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

3. Inserisci l'istruzione DDL DROP PLACEMENT(GoogleSQL, PostgreSQL).

   Ad esempio, puoi eseguire il seguente comando per eliminare la tabella di posizionamento europeplacement:

   GoogleSQL

   DROP PLACEMENT europeplacement;
   

   PostgreSQL

   DROP PLACEMENT europeplacement;
   

gcloud

Per eliminare un posizionamento con il comando gcloud CLI, utilizza gcloud spanner databases ddl update.

Ad esempio, elimina il posizionamento europeplacement:

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="DROP PLACEMENT europeplacement"

Errori di eliminazione del posizionamento

Se il posizionamento è in uso, l'DROP PLACEMENT operazione non riesce e viene visualizzato un messaggio di errore simile al seguente: "Statement failed: Placement PLACEMENT_NAME can't be dropped because it is in use by placement table PLACEMENT_TABLE_NAME.". Se riscontri questo errore, completa i seguenti passaggi:

1. Modifica l'applicazione per interrompere l'inserimento o l'aggiornamento delle righe con il posizionamento che vuoi eliminare.

2. Esegui una delle seguenti operazioni:

   • Sposta le righe di posizionamento esistenti che utilizzano il posizionamento che vuoi eliminare in un altro posizionamento con un'istruzione DML partizionata come la seguente:

     UPDATE PLACEMENT_TABLE_NAME SET LOCATION = NEW_PLACEMENT_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

   • Elimina le righe di posizionamento con un'istruzione DML partizionata come la seguente:

     DELETE FROM PLACEMENT_TABLE_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

     Le istruzioni DML specifiche per il posizionamento precedenti funzionano solo con DML partizionato. Non riusciranno come istruzioni DML regolari. Per ulteriori informazioni, consulta la sezione Limitazioni. Puoi anche utilizzare l'API Mutation per spostare o eliminare le righe di posizionamento.

Annullare un'operazione DROP PLACEMENT

Puoi annullare un'operazione DROP PLACEMENT in qualsiasi momento prima che l'operazione a lunga esecuzione elimini completamente il posizionamento dallo schema del database. Per informazioni dettagliate su come ottenere l'ID dell'operazione a lunga esecuzione per controllare lo stato o annullare l'operazione, consulta la pagina Gestire e osservare le operazioni a lunga esecuzione.

Creare una tabella con una chiave di posizionamento

Console

1. Nel menu di navigazione, fai clic su Spanner Studio.
2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

3. Inserisci l'istruzione DDL CREATE TABLE (GoogleSQL, PostgreSQL).

   Ad esempio, puoi creare una tabella Singers che utilizza una chiave di posizionamento per partizionare i dati dei cantanti:

   GoogleSQL

   CREATE TABLE Singers (
     SingerId INT64 NOT NULL,
     SingerName STRING(MAX) NOT NULL,
     ...
     Location STRING(MAX) NOT NULL PLACEMENT KEY
   ) PRIMARY KEY (SingerId);
   

   PostgreSQL

   CREATE TABLE Singers (
     SingerId bigint PRIMARY KEY,
     SingerName varchar(1024),
     ...
     Location varchar(1024) NOT NULL PLACEMENT KEY
   );
   

gcloud

Per creare una tabella, utilizza gcloud spanner databases ddl update.

Ad esempio, puoi creare una tabella Singers che utilizza una chiave di posizionamento per partizionare i dati dei cantanti:

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE TABLE Singers ( SingerId INT64 NOT NULL, SingerName STRING(MAX) NOT NULL, Location STRING(MAX) NOT NULL PLACEMENT KEY ) PRIMARY KEY (SingerId);"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE TABLE Singers ( SingerId bigint PRIMARY KEY, SingerName varchar(1024), Location varchar(1024) NOT NULL PLACEMENT KEY );"

Modificare una tabella con una chiave di posizionamento

Non puoi eliminare una chiave di posizionamento da una tabella. Inoltre, non puoi aggiungere una chiave di posizionamento a una tabella dopo la sua creazione. Tuttavia, puoi utilizzare l'istruzione DDL ALTER TABLE (GoogleSQL, PostgreSQL) per modificare altri campi in tabella, ad esempio aggiungendo ed eliminando colonne di chiavi non di posizionamento.

Eliminare una tabella con una chiave di posizionamento

Prima di eliminare una tabella con una chiave di posizionamento, devi:

1. Eliminare tutte le righe nella tabella di posizionamento.
2. Attendere il version_retention_period per il database di passare. Per ulteriori informazioni, consulta la pagina Recupero point-in-time. Quindi, segui questi passaggi:

Console

1. Nel menu di navigazione, fai clic su Spanner Studio.
2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

3. Inserisci l'istruzione DDL DROP TABLE (GoogleSQL, PostgreSQL).

   Ad esempio, elimina la tabella Singers:

   DROP TABLE Singers;
   

gcloud

Per eliminare una tabella, utilizza gcloud spanner databases ddl update.

Ad esempio, elimina la tabella Singers:

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="DROP TABLE Singers"

Inserire una riga in una tabella di posizionamento

Console

1. Nel menu di navigazione, fai clic su Spanner Studio.
2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

3. Inserisci l'istruzione DDL INSERT INTO (GoogleSQL, PostgreSQL).

   Ad esempio, aggiungi un cantante, Marc Richards, alla tabella Singers e partizionala in europeplacement:

   INSERT INTO Singers(SingerId, SingerName, Location)
   VALUES (1, 'Marc Richards', 'europeplacement')
   

gcloud

Per scrivere dati in una tabella, utilizza gcloud spanner rows insert.

Ad esempio, aggiungi un cantante, Marc Richards, alla tabella Singers e partizionala in europeplacement:

gcloud spanner rows insert --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,SingerName='Marc Richards',Location='europeplacement'

Aggiornare una riga in una tabella di posizionamento

Console

1. Nel menu di navigazione, fai clic su Spanner Studio.
2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

3. Utilizza DML o mutazioni per aggiornare i dati in una tabella di posizionamento.

   Ad esempio, aggiorna il nome di singerid=1 nella tabella Singers a Catalina Smith:

   UPDATE Singers s
   SET s.name='Catalina Smith'
   WHERE s.id=1;
   

gcloud

Per aggiornare i dati in una tabella di posizionamento, utilizza gcloud spanner rows update.

Ad esempio, aggiorna il nome di singerid=1 nella tabella Singers a Catalina Smith:

gcloud spanner rows update --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,SingerName='Catalina Smith'

Spostare una riga in una tabella di posizionamento

Console

1. Crea una nuova partizione dell'istanza e un nuovo posizionamento, se non l'hai già fatto.
2. Nel menu di navigazione, fai clic su Spanner Studio.
3. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

4. Utilizza DML o mutazioni per spostare i dati nella nuova partizione dell'istanza.

   Ad esempio, sposta singerid=1 nella tabella Singers in asiaplacement:

   UPDATE Singers s
   SET s.location='asiaplacement'
   WHERE s.id=1;
   

gcloud

Dopo aver creato la partizione dell'istanza e il posizionamento in cui vuoi spostare i dati, utilizza gcloud spanner rows update.

Ad esempio, sposta singerid=1 nella tabella Singers in asiaplacement:

gcloud spanner rows update --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,Location='asiaplacement'

Eliminare una riga in una tabella di posizionamento

Console

1. Nel menu di navigazione, fai clic su Spanner Studio.
2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

3. Utilizza DML o mutazioni per eliminare i dati.

   Ad esempio, elimina singerid=1 nella tabella Singers:

   DELETE FROM Singers s
   WHERE s.id=1;
   

gcloud

Per eliminare i dati, utilizza gcloud spanner rows delete.

Ad esempio, elimina singerid=1 nella tabella Singers:

gcloud spanner rows delete --table=Singers --database=example-db \
  --instance=test-instance --keys=1

Eseguire query sui dati in una tabella di posizionamento

Console

1. Nel menu di navigazione, fai clic su Spanner Studio.
2. Nella pagina Spanner Studio, fai clic su Nuova scheda o utilizza la scheda dell'editor vuota.

3. Esegui la query.

   Ad esempio, esegui una query sulla tabella Singers:

   SELECT * FROM Singers s WHERE s.SingerId=1;
   

gcloud

Per eseguire query sui dati, utilizza gcloud spanner databases execute-sql.

Ad esempio, esegui una query sulla tabella Singers:

gcloud spanner databases execute-sql example-db \
  --instance=test-instance \
  --sql='SELECT * FROM Singers s WHERE s.SingerId=1'

Passaggi successivi

• Scopri di più sul partizionamento geografico.

• Scopri come creare e gestire le partizioni dell'istanza.