Creare e gestire i posizionamenti dei dati

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

Per saperne di più sul funzionamento del partizionamento geografico, consulta la panoramica del partizionamento geografico.

Gestisci 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 dei client riguardi dati all'interno della stessa regione o al di fuori della regione e dall'utilizzo o meno di una configurazione multiregionale. 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 dove risiedono i metadati di routing in base alle seguenti impostazioni:

  • TRUE: se impostato su TRUE, i metadati di routing si trovano nella stessa partizione di istanza dei dati. I metadati di routing sono suddivisi in shard per regione. In questo modo, si riduce la latenza per le richieste di dati all'interno della 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 il routing dei metadati. Tuttavia, questa impostazione potrebbe aumentare la latenza per le richieste esterne alla regione, per le ricerche negative in cui non esistono righe di posizionamento e per le query che richiedono un indice globale.

    Consigliamo questa impostazione se prevedi che la maggior parte delle richieste di dati utente venga effettuata all'interno della stessa regione del client e la partizione predefinita non ha regioni di lettura/scrittura o di sola lettura collocate con tutte le partizioni dell'istanza.

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

    Consigliamo questa impostazione se prevedi che i client cerchino spesso dati al di fuori della regione, ad esempio un client nella regione UE che cerca dati per gli utenti negli Stati Uniti.

    Prendi in considerazione questa impostazione anche se la partizione dell'istanza predefinita utilizza una configurazione multiregionale che fornisce regioni di lettura/scrittura o di sola lettura collocate 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. Pertanto, tutte le regioni con partizioni di istanze hanno una replica dei metadati di routing. In questo modo, sia le richieste all'interno che all'esterno della regione possono cercare al volo i metadati di routing localmente.

Imposta l'opzione per_placement_routing_metadata

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

Per impostare l'opzione per_placement_routing_metadata, aggiorna lo schema del database. Per informazioni su altri modi per aggiornare uno schema, ad esempio le librerie client o le API REST e RPC, consulta Apporta aggiornamenti allo schema.

Seleziona una delle seguenti opzioni:

Console

  1. Nella console Google Cloud , vai alla pagina Istanze.

    Vai a Istanze

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

  3. Seleziona il database in cui vuoi impostare i metadati di routing.

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

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

  6. Inserisci l'istruzione DDL ALTER DATABASE (GoogleSQL, PostgreSQL):

    GoogleSQL

    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 per_placement_routing_metadata. Se TRUE, i metadati di routing si trovano nella stessa partizione dell'istanza dei dati. Se FALSE, i metadati di routing si trovano nella partizione dell'istanza predefinita.

    PostgreSQL

    ALTER DATABASE "DATABASE_NAME"
      SET spanner.per_placement_routing_metadata = METADATA_BOOLEAN;
    

    Sostituisci quanto segue:

    • DATABASE_NAME: il nome del database.
    • METADATA_BOOLEAN: il valore per_placement_routing_metadata. Se TRUE, i metadati di routing si trovano nella stessa partizione dell'istanza dei dati. Se FALSE, i metadati di routing si trovano nella partizione dell'istanza predefinita.
  7. Fai clic su Esegui.

gcloud

Per impostare l'opzione per_placement_routing_metadata con Google Cloud CLI, utilizza gcloud spanner databases ddl update:

GoogleSQL

gcloud spanner databases ddl update DATABASE_NAME \
    --instance=INSTANCE_ID \
    --ddl='ALTER DATABASE `DATABASE_NAME`
      SET OPTIONS (per_placement_routing_metadata = METADATA_BOOLEAN)'

Sostituisci quanto segue:

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

PostgreSQL

gcloud spanner databases ddl update DATABASE_NAME \
    --instance=INSTANCE_ID \
    --ddl='ALTER DATABASE "DATABASE_NAME"
      SET spanner.per_placement_routing_metadata = METADATA_BOOLEAN'

Sostituisci quanto segue:

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

Crea un posizionamento dei dati

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

Console

  1. Vai alla pagina Istanze nella console Google Cloud .

    Istanze

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

  3. Seleziona il database in 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 vuota dell'editor.

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

    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 Explorer oggetti per visualizzare, cercare e interagire con gli oggetti Placement. Per saperne di più, consulta Esplora 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 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')"

Imposta il leader predefinito per un posizionamento

Puoi impostare la regione leader predefinita di un posizionamento se la sua località si trova in una multi-regione. La nuova regione leader deve essere una delle due regioni di lettura/scrittura all'interno della località di posizionamento multi-regione. Per saperne di più, consulta le tabelle Configurazioni multiregionali disponibili.

Se non imposti una regione leader, il posizionamento utilizza la regione leader predefinita specificata dalla località. Per un elenco delle regione leader per ogni località multiregionale, consulta le tabelle Configurazioni multiregionali disponibili. 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 console Google Cloud .

    Istanze

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

  3. Seleziona il database in 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 vuota dell'editor.

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

    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 Explorer oggetti per visualizzare, cercare e interagire con gli oggetti Placement. Per saperne di più, consulta Esplora 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')"

Elimina un posizionamento dei dati

Prima di eliminare un posizionamento, devi rimuovere tutti i dati delle righe dal posizionamento. Dopo averlo fatto, puoi utilizzare la console Google Cloud 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 vuota dell'editor.
  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, posizionamento di rilascio europeplacement:

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

Errori di posizionamento dei drop

Se il posizionamento è in uso, l'operazione DROP PLACEMENT non va a buon fine e viene visualizzato un messaggio di errore come: "Istruzione non riuscita: il posizionamento PLACEMENT_NAME non può essere eliminato perché è in uso dalla tabella di posizionamento 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. Uno dei seguenti:

    • 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 dei posizionamenti con un'istruzione DML partizionata come la seguente:

      DELETE FROM PLACEMENT_TABLE_NAME
      WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
      

      Le istruzioni DML precedenti specifiche per il posizionamento funzionano solo con DML partizionato. Non andranno a buon fine come le normali istruzioni DML. Per ulteriori informazioni, vedi Limitazioni. Puoi anche utilizzare l'API di mutazione per spostare o eliminare le righe di posizionamento.

Annulla 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 operazione a lunga esecuzione per controllare lo stato o annullare l'operazione, consulta Gestisci e osserva le operazioni a lunga esecuzione.

Crea 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 );"

Modifica 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 averla creata. Tuttavia, puoi utilizzare l'istruzione DDL ALTER TABLE (GoogleSQL, PostgreSQL) per modificare altri campi della tabella, ad esempio aggiungendo ed eliminando colonne chiave non di posizionamento.

Elimina una tabella con una chiave di posizionamento

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

  1. Elimina tutte le righe nella tabella dei posizionamenti.
  2. Attendi che il version_retention_period per il database venga superato. Per saperne di più, consulta Recupero point-in-time. Poi 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"

Inserisci 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'

Aggiorna 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 le mutazioni per aggiornare i dati in una tabella di posizionamento.

    Ad esempio, aggiorna il nome di singerid=1 nella tabella Singers in 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 in Catalina Smith:

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

Sposta una riga in una tabella di posizionamento

Console

  1. Se non l'hai ancora fatto, crea una nuova partizione e un nuovo posizionamento dell'istanza.
  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 le 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 e la posizione dell'istanza 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'

Elimina 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 le 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

Esegui 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