Conéctate a Spanner

Como administrador de BigQuery, puedes crear una conexión para acceder a los datos de Spanner. Esta conexión permite que los analistas de datos consulten datos en Spanner.

Antes de comenzar

Crea conexiones de Spanner

Selecciona una de las opciones siguientes:

Console

  1. Ve a la página de BigQuery.

    Ir a BigQuery

  2. En el panel Explorador, haz clic en Agregar y, luego, selecciona Conexiones a la fuente de datos externa.

  3. En el panel Fuente de datos externa, ingresa la siguiente información:

    • En Connection type (Tipo de conexión), selecciona Cloud Spanner.
    • En ID de conexión, ingresa un identificador para el recurso de conexión. Se permiten letras, números y guiones bajos.
    • En Tipo de ubicación, selecciona una ubicación (o región) de BigQuery que sea compatible con la región de la fuente de datos externa.
    • En Nombre descriptivo (Friendly name), ingresa un nombre fácil de usar para la conexión, como My connection resource (opcional). El nombre descriptivo puede ser cualquier valor que te ayude a identificar el recurso de conexión si necesitas modificarlo más adelante.
    • En Descripción, ingresa una descripción para este recurso de conexión (opcional).
    • En Nombre de la base de datos, ingresa el nombre de la base de datos de Spanner en el siguiente formato: "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
    • Para realizar lecturas paralelas, selecciona Leer datos en paralelo (opcional). Spanner puede dividir determinadas consultas en partes más pequeñas, o particiones, y recuperar las particiones en paralelo. Para obtener más información, consulta Lee datos en paralelo en la documentación de Spanner. Esta opción está restringida a consultas cuyo primer operador en el plan de ejecución sea un operador de unión distribuida. Otras consultas muestran un error. A fin de ver el plan de ejecución de consultas para una consulta de Spanner, revisa Comprende cómo Spanner ejecuta consultas.
    • En Rol de la base de datos, ingresa el nombre de una función de base de datos de Spanner (opcional). Si no está vacío, esta conexión consulta a Spanner mediante esta función de base de datos de forma predeterminada. Los usuarios del control de acceso detallado de Spanner que envían consultas a través de esta conexión deben tener el acceso a este rol por su administrador, y la función de base de datos debe tener el privilegio SELECT en todos los objetos de esquema especificados en consultas externas. Para obtener información sobre el control de acceso detallado, consulta Información sobre el control de acceso detallado.
    • Opcional: Para habilitar Data Boost, selecciona Usar Spanner Data Boost. Data Boost te permite ejecutar consultas de estadísticas y exportaciones de datos con un impacto casi nulo en las cargas de trabajo existentes de la instancia de BigQuery aprovisionada. Para habilitar el boosting de datos, selecciona Data Boost y Leer datos en paralelo.

  4. Haz clic en Crear conexión (Create connection).

bq

Para crear la conexión, usa el comando bq mk con la marca --connection.

bq mk --connection \
    --connection_type=CLOUD_SPANNER \
    --properties='PROPERTIES' \
    --location=LOCATION \
    --display_name='FRIENDLY_NAME' \
    --description 'DESCRIPTION' \
    CONNECTION_ID

Reemplaza lo siguiente:

  • PROPERTIES es un objeto JSON con los siguientes campos:

    • "database" es la base de datos de Spanner para la conexión.

      Especifica el valor como una string con el siguiente formato: "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE".

    • "use_parallelism" es opcional si true. Esta conexión realiza lecturas paralelas.

      El valor predeterminado es false. Spanner puede dividir determinadas consultas en partes más pequeñas, o particiones, y recuperar las particiones en paralelo. Para obtener más información, consulta Lee datos en paralelo en la documentación de Spanner. Esta opción está restringida a consultas cuyo primer operador en el plan de ejecución sea un operador de unión distribuida. Otras consultas muestran un error. A fin de ver el plan de ejecución de consultas para una consulta de Spanner, revisa Comprende cómo Spanner ejecuta consultas.

    • "database_role": Si no está vacío, esta conexión consulta Spanner mediante este rol de base de datos (opcional). Los usuarios del control de acceso detallado de Spanner que envían consultas a través de esta conexión deben tener el acceso a este rol por su administrador, y la función de base de datos debe tener el privilegio SELECT en todos los objetos de esquema especificados en consultas externas.

      Si no se especifica, la conexión se autentica con las funciones predefinidas de IAM para Spanner, y se debe haber otorgado la función de IAM roles/spanner.databaseReader al principal que ejecuta consultas con esta conexión.

      Para obtener información sobre el control de acceso detallado, consulta Información sobre el control de acceso detallado.

    • "useDataBoost": (Opcional) Si es true, esta conexión permite a los usuarios usar Data Boost. Data Boost permite a los usuarios ejecutar consultas federadas en una capacidad de procesamiento independiente y separada, distinta de la de las instancias aprovisionadas para evitar afectar las cargas de trabajo existentes. Para habilitar el boosting de datos, establece "useDataBoost" en true y "use_parallelism" en true.

      Para usar Data Boost, la principal que ejecuta consultas con esta conexión debe tener el permiso spanner.databases.useDataBoost. Este permiso se incluye de forma predeterminada en los roles roles/spanner.admin y roles/spanner.databaseAdmin.

  • LOCATION es una ubicación de BigQuery que sea compatible con la región de fuente de datos externa

  • CONNECTION_ID es un identificador para el recurso de conexión.

    El ID de conexión puede contener letras, números y guiones bajos. Si no proporcionas un ID de conexión, BigQuery genera de forma automática un ID único.

    En el siguiente ejemplo, se crea un recurso de conexión nuevo llamado my_connection_id.

    bq mk --connection \
  --connection_type='CLOUD_SPANNER' \
  --properties='{"database":"projects/my_project/instances/my_instance/databases/database1"}' \
  --project_id=federation-test \
  --location=us \
  my_connection_id

API

Llama al método CreateConnection dentro del servicio ConnectionService.

Comparte conexiones con usuarios

Puedes otorgar los siguientes roles para permitir que los usuarios consulten datos y administren conexiones:

  • roles/bigquery.connectionUser: Permite que los usuarios usen conexiones para conectarse con fuentes de datos externas y ejecutar consultas en ellas.

  • roles/bigquery.connectionAdmin: Permite que los usuarios administren conexiones.

Para obtener más información sobre los roles y los permisos de IAM en BigQuery, consulta Roles y permisos predefinidos.

Selecciona una de las opciones siguientes:

Console

  1. Ve a la página de BigQuery.

    Ir a BigQuery

    Las conexiones se enumeran en tu proyecto, en un grupo llamado Conexiones externas.

  2. En el panel Explorador, haz clic en el nombre de tu proyecto > Conexiones externas > conexión.

  3. En el panel Detalles, haz clic en Compartir para compartir una conexión. A continuación, sigue estos pasos:

    1. En el cuadro de diálogo Permisos de conexión, agrega o edita las principales para compartir la conexión con otros principales.

    2. Haz clic en Guardar.

bq

No puedes compartir una conexión con la herramienta de línea de comandos de bq. Para compartir una conexión, usa la consola de Google Cloud o el método de la API de conexiones de BigQuery.

API

Consulta el método projects.locations.connections.setIAM en la sección de referencia de la API de REST de las conexiones de BigQuery y proporciona una instancia del recurso policy.

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:example-analyst-group@google.com")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

¿Qué sigue?