Crea y administra particiones

Vista previa — Geo-partitioning

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: Esta función está disponible en la edición Enterprise Plus de Spanner. Para obtener más información, consulta la descripción general de las ediciones de Spanner.

En esta página, se describe cómo crear y administrar particiones de Spanner.

Antes de comenzar

Para usar particiones, debes configurar la opción de base de datos opt_in_dataplacement_preview en tu base de datos vacía:

Console

1. Ve a la página Instancias en la consola de Google Cloud .

   Instancias

2. Selecciona la instancia en la que deseas agregar particiones.

3. Selecciona la base de datos vacía en la que deseas particionar los datos.

4. En el menú de navegación, haz clic en Spanner Studio.

5. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

6. Ingresa la siguiente sentencia DDL ALTER DATABASE.

   GoogleSQL

   ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);
   

   Reemplaza DATABASE_ID por el identificador único de tu base de datos.

   PostgreSQL

   ALTER DATABASE DATABASE_ID SET "spanner.opt_in_dataplacement_preview" = TRUE;
   

   Reemplaza DATABASE_ID por el identificador único de tu base de datos.

7. Haz clic en Ejecutar.

gcloud

Para establecer la opción de base de datos opt_in_dataplacement_preview, usa gcloud spanner databases ddl update.

GoogleSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);"

Reemplaza lo siguiente:

• DATABASE_ID: Es el identificador permanente de tu base de datos de Spanner.
• INSTANCE_ID: El identificador permanente de tu instancia de Spanner.

PostgreSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET "spanner.opt_in_dataplacement_preview" = TRUE"

Reemplaza lo siguiente:

• DATABASE_ID: Es el identificador permanente de tu base de datos de Spanner.
• INSTANCE_ID: El identificador permanente de tu instancia de Spanner.

Cómo crear una partición

Console

1. En la consola de Google Cloud , abre la página Spanner.

   Ir a Spanner

2. Selecciona la instancia en la que deseas agregar particiones.

3. En el menú de navegación, selecciona Particiones.

4. Haz clic en Crear partición.

5. Ingresa un ID de partición para identificarla de forma permanente. El ID de partición también debe ser único en tu proyecto de Google Cloud . No podrás cambiar el ID de la partición más adelante.

6. En la sección Elige una configuración, selecciona Regional o Multirregión. Como alternativa, si deseas comparar las especificaciones entre las regiones, haz clic en Comparar configuraciones de región.

7. Selecciona una configuración en el menú desplegable.

8. En la sección Asignar capacidad de procesamiento, en Unidad, haz clic en una de las siguientes opciones:

   • Unidades de procesamiento para particiones de instancias pequeñas.
   • Nodos para instancias grandes. Un nodo equivale a 1,000 unidades de procesamiento.

9. Ingresa un valor para la unidad seleccionada.

   Tu partición debe tener al menos un nodo o 1,000 unidades de procesamiento.

10. Haz clic en Crear para crear la partición.

gcloud

Para crear una partición, usa gcloud beta spanner instance-partitions create.

gcloud beta spanner instance-partitions create PARTITION_ID \
  --config=PARTITION_CONFIG \
  --description="PARTITION_DESCRIPTION" \
  --instance=INSTANCE_ID \
  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]

Reemplaza lo siguiente:

• PARTITION_ID: El identificador de partición permanente que es único dentro de tu proyecto de Google Cloud . No puedes cambiar el ID de la partición más adelante.
• PARTITION_CONFIG: Es el identificador permanente de la configuración de tu partición, que define la ubicación geográfica de la partición y afecta dónde se almacenan los datos.
• PARTITION_DESCRIPTION: Es el nombre que se mostrará para la partición en la consola de Google Cloud . El nombre de la partición debe ser único en tu proyecto de Google Cloud .
• INSTANCE_ID: Es el identificador permanente de tu instancia de Spanner en la que reside esta partición.
• NODE_COUNT: Es la capacidad de procesamiento de la partición, expresada como una cantidad de nodos. Un nodo equivale a 1,000 unidades de procesamiento.
• PROCESSING_UNIT_COUNT: Es la capacidad de procesamiento de la instancia, expresada como una cantidad de unidades de procesamiento. Tu partición debe tener al menos 1,000 unidades de procesamiento. Ingresa cantidades en múltiplos de 1,000 (1,000, 2,000, 3,000, etcétera).

Por ejemplo, para crear una partición europe-partition en eur3 con 5 nodos, ejecuta lo siguiente:

  gcloud beta spanner instance-partitions create europe-partition --config=eur3 \
    --description="europe-partition" --instance=test-instance --nodes=5

Bibliotecas cliente

C++

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Spanner, consulta Bibliotecas cliente de Spanner.

void CreateInstancePartition(
    google::cloud::spanner_admin::InstanceAdminClient client,
    std::string const& project_id, std::string const& instance_id,
    std::string const& instance_partition_id) {
  auto project = google::cloud::Project(project_id);
  auto in = google::cloud::spanner::Instance(project_id, instance_id);
  auto config = project.FullName() + "/instanceConfigs/nam3";

  google::spanner::admin::instance::v1::CreateInstancePartitionRequest request;
  request.set_parent(in.FullName());
  request.set_instance_partition_id(instance_partition_id);
  request.mutable_instance_partition()->set_display_name(
      "Test instance partition");
  request.mutable_instance_partition()->set_node_count(1);
  request.mutable_instance_partition()->set_config(config);

  auto instance_partition = client.CreateInstancePartition(request).get();
  if (!instance_partition) throw std::move(instance_partition).status();
  std::cout << "Created instance partition [" << instance_partition_id << "]:\n"
            << instance_partition->DebugString();
}

C#

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Spanner, consulta Bibliotecas cliente de Spanner.

using Google.Cloud.Spanner.Admin.Instance.V1;
using Google.Cloud.Spanner.Common.V1;
using Google.LongRunning;
using System;

public class CreateInstancePartitionSample
{
    public InstancePartition CreateInstancePartition(string projectId, string instanceId, string instancePartitionId)
    {
        // Create the InstanceAdminClient instance.
        InstanceAdminClient instanceAdminClient = InstanceAdminClient.Create();

        // Initialize request parameters.
        InstancePartition partition = new InstancePartition
        {
            DisplayName = "This is a display name.",
            NodeCount = 1,
            ConfigAsInstanceConfigName = InstanceConfigName.FromProjectInstanceConfig(projectId, "nam3"),
        };
        InstanceName instanceName = InstanceName.FromProjectInstance(projectId, instanceId);

        // Make the CreateInstancePartition request.
        Operation<InstancePartition, CreateInstancePartitionMetadata> response = instanceAdminClient.CreateInstancePartition(instanceName, partition, instancePartitionId);

        Console.WriteLine("Waiting for the operation to finish.");

        // Poll until the returned long-running operation is complete.
        Operation<InstancePartition, CreateInstancePartitionMetadata> completedResponse = response.PollUntilCompleted();

        if (completedResponse.IsFaulted)
        {
            Console.WriteLine($"Error while creating instance partition: {completedResponse.Exception}");
            throw completedResponse.Exception;
        }

        Console.WriteLine($"Instance created successfully.");

        return completedResponse.Result;
    }
}

Go

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Spanner, consulta Bibliotecas cliente de Spanner.

import (
	"context"
	"fmt"
	"io"

	instance "cloud.google.com/go/spanner/admin/instance/apiv1"
	"cloud.google.com/go/spanner/admin/instance/apiv1/instancepb"
)

// Example of creating an instance partition with Go.
// projectID is the ID of the project that the new instance partition will be in.
// instanceID is the ID of the instance that the new instance partition will be in.
// instancePartitionID is the ID of the new instance partition to be created.
func createInstancePartition(w io.Writer, projectID, instanceID, instancePartitionID string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance"
	// instancePartitionID := "my-instance-partition"
	ctx := context.Background()
	instanceAdmin, err := instance.NewInstanceAdminClient(ctx)
	if err != nil {
		return err
	}
	defer instanceAdmin.Close()

	op, err := instanceAdmin.CreateInstancePartition(ctx, &instancepb.CreateInstancePartitionRequest{
		Parent:              fmt.Sprintf("projects/%s/instances/%s", projectID, instanceID),
		InstancePartitionId: instancePartitionID,
		InstancePartition: &instancepb.InstancePartition{
			Config:          fmt.Sprintf("projects/%s/instanceConfigs/%s", projectID, "nam3"),
			DisplayName:     "my-instance-partition",
			ComputeCapacity: &instancepb.InstancePartition_NodeCount{NodeCount: 1},
		},
	})
	if err != nil {
		return fmt.Errorf("could not create instance partition %s: %w", fmt.Sprintf("projects/%s/instances/%s/instancePartitions/%s", projectID, instanceID, instancePartitionID), err)
	}
	// Wait for the instance partition creation to finish.
	i, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("waiting for instance partition creation to finish failed: %w", err)
	}
	// The instance partition may not be ready to serve yet.
	if i.State != instancepb.InstancePartition_READY {
		fmt.Fprintf(w, "instance partition state is not READY yet. Got state %v\n", i.State)
	}
	fmt.Fprintf(w, "Created instance partition [%s]\n", instancePartitionID)
	return nil
}

Java

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Spanner, consulta Bibliotecas cliente de Spanner.

import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
import com.google.spanner.admin.instance.v1.CreateInstancePartitionRequest;
import com.google.spanner.admin.instance.v1.InstanceConfigName;
import com.google.spanner.admin.instance.v1.InstanceName;
import com.google.spanner.admin.instance.v1.InstancePartition;
import java.util.concurrent.ExecutionException;

class CreateInstancePartitionSample {

  static void createInstancePartition() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String instancePartitionId = "my-instance-partition";
    createInstancePartition(projectId, instanceId, instancePartitionId);
  }

  static void createInstancePartition(
      String projectId, String instanceId, String instancePartitionId) {
    // Set instance partition configuration.
    int nodeCount = 1;
    String displayName = "Descriptive name";

    // Create an InstancePartition object that will be used to create the instance partition.
    InstancePartition instancePartition =
        InstancePartition.newBuilder()
            .setDisplayName(displayName)
            .setNodeCount(nodeCount)
            .setConfig(InstanceConfigName.of(projectId, "nam3").toString())
            .build();

    try (Spanner spanner =
            SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
        InstanceAdminClient instanceAdminClient = spanner.createInstanceAdminClient()) {

      // Wait for the createInstancePartition operation to finish.
      InstancePartition createdInstancePartition =
          instanceAdminClient
              .createInstancePartitionAsync(
                  CreateInstancePartitionRequest.newBuilder()
                      .setParent(InstanceName.of(projectId, instanceId).toString())
                      .setInstancePartitionId(instancePartitionId)
                      .setInstancePartition(instancePartition)
                      .build())
              .get();
      System.out.printf(
          "Instance partition %s was successfully created%n", createdInstancePartition.getName());
    } catch (ExecutionException e) {
      System.out.printf(
          "Error: Creating instance partition %s failed with error message %s%n",
          instancePartition.getName(), e.getMessage());
    } catch (InterruptedException e) {
      System.out.println(
          "Error: Waiting for createInstancePartition operation to finish was interrupted");
    }
  }
}

Node.js

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Spanner, consulta Bibliotecas cliente de Spanner.

// 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 instancePartitionId = 'my-instance-partition';

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

// Get the instance admin client
const instanceAdminClient = spanner.getInstanceAdminClient();

// Creates a new instance partition
try {
  console.log(
    `Creating instance partition ${instanceAdminClient.instancePartitionPath(
      projectId,
      instanceId,
      instancePartitionId
    )}.`
  );
  const [operation] = await instanceAdminClient.createInstancePartition({
    instancePartitionId: instancePartitionId,
    parent: instanceAdminClient.instancePath(projectId, instanceId),
    instancePartition: {
      config: instanceAdminClient.instanceConfigPath(projectId, 'nam3'),
      nodeCount: 1,
      displayName: 'Test instance partition',
    },
  });

  console.log(
    `Waiting for operation on ${instancePartitionId} to complete...`
  );
  await operation.promise();

  console.log(`Created instance partition ${instancePartitionId}.`);
} catch (err) {
  console.error('ERROR:', err);
}

PHP

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Spanner, consulta Bibliotecas cliente de Spanner.

use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;
use Google\Cloud\Spanner\Admin\Instance\V1\CreateInstancePartitionRequest;
use Google\Cloud\Spanner\Admin\Instance\V1\InstancePartition;

/**
 * Creates an instance partition.
 * Example:
 * ```
 * create_instance_partition($projectId, $instanceId, $instancePartitionId);
 * ```
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $instanceId The Spanner instance ID.
 * @param string $instancePartitionId The instance partition ID.
 */
function create_instance_partition(string $projectId, string $instanceId, string $instancePartitionId): void
{
    $instanceAdminClient = new InstanceAdminClient();

    $instanceName = $instanceAdminClient->instanceName($projectId, $instanceId);
    $instancePartitionName = $instanceAdminClient->instancePartitionName($projectId, $instanceId, $instancePartitionId);
    $configName = $instanceAdminClient->instanceConfigName($projectId, 'nam3');

    $instancePartition = (new InstancePartition())
        ->setConfig($configName)
        ->setDisplayName('Test instance partition.')
        ->setNodeCount(1);

    $operation = $instanceAdminClient->createInstancePartition(
        (new CreateInstancePartitionRequest())
        ->setParent($instanceName)
        ->setInstancePartitionId($instancePartitionId)
        ->setInstancePartition($instancePartition)
    );

    print('Waiting for operation to complete...' . PHP_EOL);
    $operation->pollUntilComplete();

    printf('Created instance partition %s' . PHP_EOL, $instancePartitionId);
}

Python

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Spanner, consulta Bibliotecas cliente de Spanner.

def create_instance_partition(instance_id, instance_partition_id):
    """Creates an instance partition."""
    from google.cloud.spanner_admin_instance_v1.types import spanner_instance_admin

    spanner_client = spanner.Client()
    instance_admin_api = spanner_client.instance_admin_api

    config_name = "{}/instanceConfigs/nam3".format(spanner_client.project_name)

    operation = spanner_client.instance_admin_api.create_instance_partition(
        parent=instance_admin_api.instance_path(spanner_client.project, instance_id),
        instance_partition_id=instance_partition_id,
        instance_partition=spanner_instance_admin.InstancePartition(
            config=config_name,
            display_name="Test instance partition",
            node_count=1,
        ),
    )

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)

    print("Created instance partition {}".format(instance_partition_id))

Describe una partición

gcloud

Para describir una partición, usa gcloud beta spanner instance-partitions describe.

gcloud beta spanner instance-partitions describe PARTITION_ID \
  --instance=INSTANCE_ID

Reemplaza lo siguiente:

• PARTITION_ID: Es el identificador permanente de la partición.
• INSTANCE_ID: El identificador permanente de la instancia.

Por ejemplo, para describir la partición europe-partition, ejecuta lo siguiente:

  gcloud beta spanner instance-partitions describe europe-partition
    --instance=test-instance

Cómo enumerar particiones

Console

1. En la consola de Google Cloud , abre la página Spanner.

   Ir a Spanner

2. Elige una instancia de la lista.

3. En el menú de navegación, selecciona Particiones.

   Se muestra una lista de las particiones asociadas con esa instancia.

gcloud

Para enumerar tus particiones, usa gcloud beta spanner instance-partitions list.

gcloud beta spanner instance-partitions list --instance=INSTANCE_ID

Gcloud CLI imprime una lista de tus particiones de Spanner, junto con el ID, el nombre visible, la configuración y la capacidad de procesamiento de cada partición.

Cómo editar una partición

En la siguiente sección, se explica cómo cambiar la capacidad de procesamiento de tu partición. No puedes cambiar el ID, el nombre ni la configuración de la partición.

Cambia la capacidad de procesamiento

Debes aprovisionar suficiente capacidad de procesamiento para mantener el uso de la CPU y el uso de almacenamiento por debajo de los valores máximos recomendados. Para obtener más información, consulta las cuotas y los límites de Spanner.

Si deseas aumentar la capacidad de procesamiento de una partición, tu proyecto de Google Cloud debe tener una cuota suficiente para agregar la capacidad de procesamiento. El tiempo que tarda en completarse la solicitud de aumento depende del tamaño de la solicitud. En la mayoría de los casos, las solicitudes se completan en unos minutos. En ocasiones excepcionales, el aumento de escala puede tardar hasta una hora en completarse.

Console

1. En la consola de Google Cloud , abre la página Spanner.

   Ir a Spanner

2. Elige una instancia de la lista.

3. En el menú de navegación, selecciona Particiones.

4. En la lista de particiones, en la columna Acciones, haz clic en Más acciones y selecciona Editar.

5. Para cambiar la capacidad de procesamiento, elige una unidad de medida (unidades de procesamiento o nodos) y, luego, ingresa una cantidad. Cuando uses unidades de procesamiento, ingresa las cantidades en múltiplos de 1,000 (1,000, 2,000, 3,000, etcétera). Cada nodo equivale a 1,000 unidades de procesamiento.

   Tu partición debe tener al menos un nodo (1,000 unidades de procesamiento).

6. Haz clic en Guardar.

   Si ves un cuadro de diálogo que indica que tienes una cuota insuficiente para agregar capacidad de procesamiento , sigue las instrucciones para solicitar una cuota superior.

gcloud

Para cambiar la capacidad de procesamiento de tu partición, usa gcloud beta spanner instance-partitions update. Cuando uses este comando, especifica la capacidad de procesamiento como una cantidad de nodos o unidades de procesamiento.

gcloud beta spanner instance-partitions update PARTITION_ID /
  --instance=INSTANCE_ID /
  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]
  [--async]

Reemplaza lo siguiente:

• PARTITION_ID: Es el identificador permanente de la partición.
• INSTANCE_ID: El identificador permanente de la instancia.
• NODE_COUNT: Es la nueva capacidad de procesamiento de la partición, expresada como una cantidad de nodos. Un nodo equivale a 1,000 unidades de procesamiento.
• PROCESSING_UNIT_COUNT: Es la nueva capacidad de procesamiento de la partición, expresada como una cantidad de unidades de procesamiento. Tu partición debe tener al menos 1,000 unidades de procesamiento. Ingresa cantidades en múltiplos de 1,000 (1,000, 2,000, 3,000, etcétera).

Marcas opcionales:

• --async: Usa esta marca si deseas que tu solicitud se muestre de inmediato, sin esperar a que se complete la operación en curso.

Para verificar el estado de tu solicitud, ejecuta gcloud spanner operations describe.

Borra una partición

No puedes borrar una partición mientras esté asociada a ninguna posición o datos. Primero, debes mover los datos que se encuentran en la partición o borrar las tablas de ubicación que la usan para poder borrarla.

Console

1. En la consola de Google Cloud , abre la página Spanner.

   Ir a Spanner

2. Elige una instancia de la lista.

3. En el menú de navegación, selecciona Particiones.

4. En la lista de particiones, en la columna Acciones, haz clic en Más acciones y selecciona Borrar.

5. Sigue las instrucciones para confirmar que quieres borrar la partición.

6. Haz clic en Borrar.

gcloud

Usa el comando gcloud beta spanner instance-partitions delete.

gcloud beta spanner instance-partitions delete PARTITION_ID
  --instance=INSTANCE_ID

¿Qué sigue?

• Obtén información para crear y administrar la tabla y las claves de posición.