הרצת שאילתות מאוחדות באמצעות Data Boost

בדף הזה מוסבר איך להשתמש ב-Spanner Data Boost כשמריצים שאילתות לכמה מסדי נתונים מ-BigQuery למסד נתונים של Spanner. כשמשתמשים ב-Data Boost, השאילתות לכמה מסדי נתונים פועלות עם השפעה מינימלית על עומסי העבודה הקיימים במכונה המוקצית של Spanner. שאילתות Data Boost מ-BigQuery למסד נתונים של Spanner יכולות לאחד נתונים מ-BigQuery עם נתונים מ-Spanner.

אתם יכולים להריץ שאילתות מאוחדות מ-BigQuery ל-Spanner באמצעות Data Boost באחת מהשיטות הבאות:

• מריצים שאילתה לכמה מסדי נתונים של Data Boost, שמשתמשת בפונקציית השאילתה לכמה מסדי נתונים EXTERNAL_QUERY.
• שימוש ב-Data Boost עם מערכי נתונים חיצוניים.

באמצעות איחוד ב-Spanner, אפשר לשלוח שאילתות מ-BigQuery לנתונים שנמצאים ב-Spanner בזמן אמת, בלי להעתיק או להעביר את הנתונים. מידע נוסף על שאילתות מאוחדות של Spanner זמין במאמר שאילתות מאוחדות של Spanner. למידע נוסף על Data Boost, קראו את הסקירה הכללית על Data Boost.

לפני שמתחילים

כדי להריץ שאילתות לכמה מסדי נתונים באמצעות Data Boost, צריך לבצע את הפעולות הבאות:

• יוצרים מכונה ומסד נתונים ב-Spanner.

• מפעילים את BigQuery Connection API.

• נותנים את הרשאות ה-IAM הנדרשות.

יצירת מכונה ומסד נתונים ב-Spanner

אם אין לכם מכונה ומסד נתונים ב-Spanner, תוכלו ליצור אותם לפי השלבים שמפורטים במאמר יצירת מסד נתונים והרצת שאילתות באמצעות מסוף Google Cloud .

הפעלת BigQuery Connection API

באמצעות BigQuery Connection API אתם יכולים לנהל את החיבורים של BigQuery למקורות נתונים חיצוניים, כמו מסד נתונים של Spanner.

• מפעילים את BigQuery Connection API, אם הוא עדיין לא מופעל.

  התפקידים שנדרשים כדי להפעיל ממשקי API

  כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

  להפעלת ה-API

למידע נוסף, קראו את המאמר BigQuery Connection API במסמכי התיעוד של BigQuery.

הענקת הרשאות IAM ל-Data Boost לחשבונות משתמשים

כדי להריץ שאילתות לכמה מסדי נתונים באמצעות Data Boost, צריך לתת לחשבון המשתמש את ההרשאות הבאות:

• ‫spanner.instances.get – מאפשרת לקבל את ההגדרות של מכונה.
• ‫spanner.databases.useDataBoost – מאפשר להשתמש במשאבי המחשוב של Spanner Data Boost כדי לעבד שאילתות מחולקות למחיצות.

למידע נוסף על ההרשאות ב-Spanner, קראו את המאמר הרשאות בניהול זהויות והרשאות גישה (IAM).

כדי לתת את ההרשאות הנדרשות, מומלץ להשתמש בתפקיד ה-IAM‏ Cloud Spanner Database Reader With DataBoost (roles/spanner.databaseReaderWithDataBoost). אתם יכולים להוסיף את התפקיד הזה לכל חשבון משתמש שצריך להריץ שאילתות לכמה מסדי נתונים באמצעות Data Boost. מידע נוסף על תפקידים מוגדרים מראש ב-Spanner במאמר יצירת תפקיד בהתאמה אישית מוסבר איך יוצרים תפקיד IAM בהתאמה אישית.

הרצת שאילתה מאוחדת של Data Boost

כדי להריץ שאילתת Data Boost מ-BigQuery למקור חיצוני, צריך חיבור של BigQuery למקור החיצוני ואת מזהה החיבור. כשמריצים שאילתה מאוחדת ב-Spanner באמצעות Data Boost, מקור הנתונים החיצוני הוא מסד נתונים של Spanner. אחרי שיוצרים את מזהה החיבור, BigQuery משתמש בו כדי להריץ שאילתת Data Boost במסד נתונים של Spanner.

כדי ליצור מזהה חיבור ל-BigQuery, אתם יכולים להשתמש באחת מהאפשרויות הבאות, ואז להשתמש במזהה החיבור כדי להריץ שאילתת Data Boost מ-BigQuery:

1. התחלה ב-Spanner – יוצרים את מזהה החיבור החיצוני של BigQuery במסוף Spanner. אחרי שיוצרים את מזהה החיבור במסוף Spanner, מועברים למסוף BigQuery כדי להריץ שאילתה מאוחדת של Data Boost למסד נתונים ב-Spanner.

2. מתחילים ב-BigQuery – יוצרים את מזהה החיבור החיצוני של Data Boost במסוף BigQuery או באמצעות כלי שורת הפקודה bq. אחרי שיוצרים את מזהה החיבור, נשארים במסוף BigQuery כדי להריץ שאילתת Data Boost מאוחדת למסד נתונים ב-Spanner.

התחלה ב-Spanner כדי להריץ שאילתת Data Boost

כדי להריץ שאילתת Data Boost מאוחדת ב-Spanner Studio:

1. נכנסים לדף Instances של Spanner במסוףGoogle Cloud .

   כניסה לדף Instances

   במסוף תוצג רשימה של מכונות Spanner.

2. בוחרים מכונה של Spanner ואז בוחרים מסד נתונים.

3. בתפריט הניווט שבדף Database overview, לוחצים על Spanner Studio.

4. לוחצים על הצגה ב-BigQuery.

5. בתיבת הדו-שיח View in BigQuery, מזינים מזהה חיבור.

   מזהה החיבור משמש ליצירת חיבור חיצוני חדש של BigQuery למסד הנתונים של Spanner. כדי להפנות לחיבור החיצוני, משתמשים בתבנית הבאה:

   PROJECT-ID.LOCATION.CONNECTION-ID
   

   אם המזהה כבר קיים, תופיע שגיאה.

6. ממלאים את שאר השדות בתיבת הדו-שיח ומבצעים את הפעולות הבאות:

   • בוחרים באפשרות Read data in parallel.
   • בוחרים באפשרות Use Spanner Data Boost.

7. לוחצים על View in BigQuery.

   ‫BigQuery Studio נפתח עם השאילתה הבאה:

   SELECT * FROM EXTERNAL_QUERY("PROJECT-ID.LOCATION.CONNECTION-ID", "SELECT * FROM INFORMATION_SCHEMA.TABLES;");
   

   אתם יכולים להחליף את זה בשאילתה לכמה מסדי נתונים. לדוגמה, אפשר ליצור שאילתה שדומה לדוגמה הבאה. בדוגמה הזו, מתבצעת שאילתה לכמה מסדי נתונים מטבלה בשם orders במסד נתונים של Spanner, והתוצאות מצורפות לטבלה ב-BigQuery בשם mydataset.customers.

   SELECT c.customer_id, c.name, rq.first_order_date
   FROM mydataset.customers AS c
   LEFT OUTER JOIN EXTERNAL_QUERY(
     'my-project.us.example-db',
     '''SELECT customer_id, MIN(order_date) AS first_order_date
     FROM orders
     GROUP BY customer_id''') AS rq
     ON rq.customer_id = c.customer_id
   GROUP BY c.customer_id, c.name, rq.first_order_date;

התחלת העבודה ב-BigQuery כדי להריץ שאילתת Data Boost

כדי ליצור חיבור של מקור נתונים חיצוני מ-BigQuery למסד נתונים ב-Spanner, ולהשתמש בחיבור הזה כדי להריץ שאילתה מאוחדת של Data Boost מ-BigQuery, בוחרים אחת מהאפשרויות הבאות:

המסוף

1. עוברים למאמר יצירת חיבורים ל-Spanner במסמכי התיעוד של BigQuery, ופועלים לפי ההוראות בכרטיסייה Console.

2. בחלונית External data source:

   • בוחרים באפשרות Read data in parallel.
   • בוחרים באפשרות Use Spanner Data Boost.

BQ

1. עוברים למאמר יצירת חיבורים ל-Spanner במסמכי התיעוד של BigQuery, ופועלים לפי ההוראות בכרטיסייה bq*.

2. מגדירים את מאפייני החיבור הבאים ל-true:

   • useParallelism
   • useDataBoost

בדוגמה הבאה משתמשים בפקודה bq mk כדי ליצור חיבור חדש בשם my_connection עם שני המאפיינים הנדרשים ל-Data Boost:

bq mk --connection --connection_type='CLOUD_SPANNER' --location='us' \
--properties='{"database":"projects/my-project/instances/my-instance/databases/my-database", "useParallelism":true, "useDataBoost": true}' my_connection

שימוש ב-Data Boost עם מערכי נתונים חיצוניים

כדי להריץ שאילתת Data Boost מ-BigQuery ל-Spanner כמקור חיצוני, אתם יכולים ליצור מערך נתונים חיצוני (שנקרא גם מערך נתונים מאוחד) ב-BigQuery שמקושר למסד נתונים קיים של GoogleSQL או PostgreSQL ב-Spanner.

שימוש בחיבור CLOUD_RESOURCE

כברירת מחדל, מערכי נתונים חיצוניים של Spanner משתמשים בפרטי כניסה של משתמשי קצה (EUC), ולכן המשתמשים צריכים גישה ישירה למסדי הנתונים שלהם ב-Spanner. המשתמשים יכולים לשלוח שאילתות למערכי הנתונים האלה אם יש להם גישה ב-Spanner.

אפשר להשתמש בחיבור CLOUD_RESOURCE במערכי נתונים חיצוניים של Spanner כדי לקיים אינטראקציה עם מסד הנתונים של Spanner, וכך לתת למשתמשים גישה לנתוני Spanner דרך BigQuery בלי לתת להם גישה ישירה למסד הנתונים של Spanner. מכיוון שחשבון השירות מהחיבור של CLOUD_RESOURCE מטפל באחזור הנתונים מ-Spanner, אתם צריכים לתת למשתמשים גישה רק למערך הנתונים החיצוני של Spanner. האצלת הגישה הזו מפרידה בין הגישה לטבלאות Spanner ממערכי נתונים חיצוניים לבין הגישה הישירה לטבלאות Spanner הבסיסיות. כדי להתחבר ל-Spanner, משתמשים בקישור למשאבים ב-Cloud שמשויך לחשבון שירות. המשתמשים יכולים לשלוח שאילתות לטבלאות Spanner האלה ממערכי נתונים חיצוניים, גם אם לא ניתנה להם גישה ב-Spanner.

לפני שיוצרים מערכי נתונים חיצוניים של Spanner באמצעות חיבור CLOUD_RESOURCE, צריך לבצע את הפעולות הבאות:

יצירת חיבור

כדי להתחבר ל-Spanner, אתם יכולים ליצור חיבור CLOUD_RESOURCE או להשתמש בחיבור קיים. חשוב ליצור את החיבור באותו מיקום שבו אתם מתכננים ליצור את קבוצת הנתונים החיצונית של Spanner.

בוחרים באחת מהאפשרויות הבאות:

המסוף

1. נכנסים לדף BigQuery.

   כניסה ל-BigQuery

2. בחלונית הימנית, לוחצים על Explorer:

   

   אם החלונית הימנית לא מוצגת, לוחצים על Expand left pane כדי לפתוח אותה.

3. בחלונית Explorer, מרחיבים את שם הפרויקט ולוחצים על Connections.

4. בדף Connections, לוחצים על Create connection.

5. בשדה Connection type, בוחרים באפשרות Vertex AI remote models, remote functions, BigLake and Spanner (Cloud Resource).

6. בשדה מזהה החיבור, נותנים שם לחיבור.

7. בשדה Location type, בוחרים מיקום לחיבור. החיבור צריך להיות באותו מיקום כמו המשאבים האחרים, למשל מערכי נתונים.

8. לוחצים על יצירת חיבור.

9. לוחצים על מעבר לחיבור.

10. בחלונית Connection info, מעתיקים את מזהה חשבון השירות כדי להשתמש בו בשלב מאוחר יותר.

SQL

משתמשים בהצהרה CREATE CONNECTION:

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. בעורך השאילתות, מזינים את ההצהרה הבאה:

   CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
   OPTIONS (
     connection_type = "CLOUD_RESOURCE",
     friendly_name = "FRIENDLY_NAME",
     description = "DESCRIPTION"
     );

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫CONNECTION_NAME: שם החיבור בפורמט PROJECT_ID.LOCATION.CONNECTION_ID,‏ LOCATION.CONNECTION_ID או CONNECTION_ID. אם לא מציינים את הפרויקט או המיקום, הם נגזרים מהפרויקט ומהמיקום שבהם ההצהרה מופעלת.
   • ‫FRIENDLY_NAME (אופציונלי): שם תיאורי לחיבור.
   • ‫DESCRIPTION (אופציונלי): תיאור של החיבור.

3. לוחצים על הפעלה.

מידע נוסף על הרצת שאילתות זמין במאמר הרצת שאילתה אינטראקטיבית.

BQ

1. בסביבה של שורת הפקודה, יוצרים חיבור:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   הפרמטר --project_id מבטל את פרויקט ברירת המחדל.

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫REGION: אזור החיבור שלכם
   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
   • ‫CONNECTION_ID: מזהה לחיבור

   כשיוצרים משאב חיבור, BigQuery יוצר חשבון שירות ייחודי של המערכת ומשייך אותו לחיבור.

   פתרון בעיות: אם מופיעה שגיאת החיבור הבאה, עדכנו את Google Cloud SDK:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. מאחזרים ומעתיקים את מזהה חשבון השירות כדי להשתמש בו בשלב מאוחר יותר:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   הפלט אמור להיראות כך:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Python

במאמר ספריות הלקוח של Spanner מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Spanner.

כדי לבצע אימות ב-Spanner, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

במאמר ספריות הלקוח של Spanner מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Spanner.

כדי לבצע אימות ב-Spanner, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Java

במאמר ספריות הלקוח של Spanner מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Spanner.

כדי לבצע אימות ב-Spanner, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

משתמשים במשאב google_bigquery_connection.

הערה: כדי ליצור אובייקטים של BigQuery באמצעות Terraform, צריך להפעיל את Cloud Resource Manager API.

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

בדוגמה הבאה נוצר קישור למשאבים ב-Cloud בשם my_cloud_resource_connection באזור US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

כך מחילים את ההגדרות של Terraform בפרויקט ב- Google Cloud :

הכנת Cloud Shell

1. מפעילים את Cloud Shell.

2. מגדירים את פרויקט ברירת המחדל ב- Google Cloud שבו רוצים להחיל את ההגדרות של Terraform.

   תצטרכו להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ותוכלו לעשות זאת בכל ספרייה.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   אם תגדירו ערכים ספציפיים בקובץ התצורה של Terraform, הם יבטלו את ערכי ברירת המחדל של משתני הסביבה.

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

   מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

   לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
4. שומרים את השינויים.
5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.

   terraform init

   אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:

   terraform init -upgrade

החלה של השינויים

1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:

   terraform apply

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

3. פותחים את הפרויקט ב- Google Cloud כדי להציג את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

הערה: בדרך כלל הנחת העבודה בדוגמאות של Terraform היא שממשקי ה-API הנדרשים מופעלים בפרויקט ב- Google Cloud .

אחרי שיוצרים את החיבור, פותחים אותו ומעתיקים את מזהה חשבון השירות מהחלונית Connection info. המזהה הזה נדרש כשמגדירים הרשאות לחיבור. כשיוצרים משאב חיבור, BigQuery יוצר חשבון שירות ייחודי של המערכת ומשייך אותו לחיבור.

הגדרת גישה

אתם צריכים לתת לחשבון השירות שמשויך לחיבור החדש גישת קריאה למסד הנתונים או למכונה של Spanner. מומלץ להשתמש בתפקיד המוגדר מראש ב-IAM "קורא מסדי נתונים של Cloud Spanner עם Data Boost" (roles/spanner.databaseReaderWithDataBoost).

כדי להעניק גישה לתפקידים ברמת מסד הנתונים לחשבון השירות שהעתקתם קודם מהחיבור, פועלים לפי השלבים הבאים:

1. נכנסים לדף Instances ב-Spanner.

   כניסה לדף המכונות

2. לוחצים על שם המכונה שמכילה את מסד הנתונים כדי לעבור לדף Instance details.

3. בכרטיסייה Overview, מסמנים את התיבה של מסד הנתונים.
   מופיע החלונית Info panel.

4. לוחצים על Add principal.

5. בחלונית Add principals, בשדה New principals, מזינים את מזהה חשבון השירות שהעתקתם קודם.

6. בשדה Select a role, בוחרים את התפקיד Cloud Spanner Database Reader with DataBoost.

7. לוחצים על Save.

יצירת מערך נתונים חיצוני

כדי ליצור קבוצת נתונים חיצונית:

המסוף

1. פותחים את הדף BigQuery במסוף Google Cloud .

   כניסה לדף BigQuery

2. בחלונית השמאלית, לוחצים על Explorer:

   

   אם החלונית הימנית לא מוצגת, לוחצים על הרחבת החלונית הימנית כדי לפתוח אותה.

3. בחלונית Explorer, בוחרים את הפרויקט שבו רוצים ליצור את מערך הנתונים.

4. לוחצים על View actions ואז על Create dataset.

5. בדף Create dataset, מבצעים את הפעולות הבאות:

   • בשדה Dataset ID, מזינים שם ייחודי למערך הנתונים.
   • בשדה Location type, בוחרים מיקום לקבוצת הנתונים, למשל us-central1 או מספר אזורים us. אחרי שיוצרים את מערך הנתונים אי אפשר לשנות את המיקום.

   • בקטע External Dataset:

     • מסמנים את התיבה לצד קישור למערך נתונים חיצוני.
     • בשדה External dataset type, בוחרים באפשרות Spanner.
     • בשדה מקור חיצוני, מזינים את המזהה המלא של מסד הנתונים ב-Spanner בפורמט הבא: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. לדוגמה: projects/my_project/instances/my_instance/databases/my_database.
     • אם רוצים, בשדה Database role מזינים את השם של תפקיד במסד הנתונים של Spanner. מידע נוסף על תפקידים במסד הנתונים שמשמשים ליצירת חיבורים ל-Spanner
     • אם רוצים ליצור את קבוצת הנתונים החיצונית באמצעות קישור למשאבים ב-Cloud, מסמנים את התיבה Use a Cloud Resource connection.

   • משאירים את שאר הגדרות ברירת המחדל כמו שהן.

6. לוחצים על Create dataset.

SQL

משתמשים בהצהרה של שפת הגדרת נתונים (DDL) של CREATE EXTERNAL SCHEMA.

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. בעורך השאילתות, מזינים את ההצהרה הבאה:

   CREATE EXTERNAL SCHEMA DATASET_NAME
     OPTIONS (
       external_source = 'SPANNER_EXTERNAL_SOURCE',
       location = 'LOCATION');
   /*
     Alternatively, create with a connection:
   */
   CREATE EXTERNAL SCHEMA DATASET_NAME
     WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
     OPTIONS (
       external_source = 'SPANNER_EXTERNAL_SOURCE',
       location = 'LOCATION');

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫DATASET_NAME: השם של מערך הנתונים החדש ב-BigQuery.
   • ‫SPANNER_EXTERNAL_SOURCE: השם המלא והתקין של מסד הנתונים ב-Spanner, עם קידומת שמזהה את המקור, בפורמט הבא: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. לדוגמה: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database או google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
   • ‫LOCATION: המיקום של מערך הנתונים החדש ב-BigQuery, לדוגמה us-central1. אחרי שיוצרים מערך נתונים, אי אפשר לשנות את המיקום שלו.
   • ‫CONNECTION_NAME (אופציונלי): השם של הקישור למשאבים ב-Cloud.

3. לוחצים על הפעלה.

מידע נוסף על הרצת שאילתות זמין במאמר הרצת שאילתה אינטראקטיבית.

BQ

בסביבה של שורת הפקודה, יוצרים מערך נתונים חיצוני באמצעות הפקודה bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

אפשר גם ליצור באמצעות חיבור:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

מחליפים את מה שכתוב בשדות הבאים:

• ‫LOCATION: המיקום של מערך הנתונים החדש ב-BigQuery, לדוגמה us-central1. אחרי שיוצרים מערך נתונים, אי אפשר לשנות את המיקום שלו. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות הקובץ .bigqueryrc.
• ‫SPANNER_EXTERNAL_SOURCE: השם המלא והתקין של מסד הנתונים ב-Spanner, עם קידומת שמזהה את המקור, בפורמט הבא: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. לדוגמה: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database או google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
• ‫DATASET_NAME: השם של מערך הנתונים החדש ב-BigQuery. כדי ליצור מערך נתונים בפרויקט שאינו פרויקט ברירת המחדל, מוסיפים את מזהה הפרויקט לשם של מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET_NAME.
• ‫CONNECTION_NAME (אופציונלי): השם של הקישור למשאבים ב-Cloud.

Terraform

משתמשים במשאב google_bigquery_dataset.

הערה: כדי ליצור אובייקטים של BigQuery באמצעות Terraform, צריך להפעיל את Cloud Resource Manager API.

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

בדוגמה הבאה נוצר מערך נתונים חיצוני של Spanner:

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

כך מחילים את ההגדרות של Terraform בפרויקט ב- Google Cloud :

הכנת Cloud Shell

1. מפעילים את Cloud Shell.

2. מגדירים את פרויקט ברירת המחדל ב- Google Cloud שבו רוצים להחיל את ההגדרות של Terraform.

   תצטרכו להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ותוכלו לעשות זאת בכל ספרייה.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   אם תגדירו ערכים ספציפיים בקובץ התצורה של Terraform, הם יבטלו את ערכי ברירת המחדל של משתני הסביבה.

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

   מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

   לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
4. שומרים את השינויים.
5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.

   terraform init

   אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:

   terraform init -upgrade

החלה של השינויים

1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:

   terraform apply

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

3. פותחים את הפרויקט ב- Google Cloud כדי להציג את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

הערה: בדרך כלל הנחת העבודה בדוגמאות של Terraform היא שממשקי ה-API הנדרשים מופעלים בפרויקט ב- Google Cloud .

API

מפעילים את ה-method‏ datasets.insert עם משאב של מערך נתונים מוגדר ושדה externalDatasetReference למסד הנתונים של Spanner.

שימו לב: השמות של הטבלאות במערכי הנתונים החיצוניים לא תלויי אותיות רישיות.

כשיוצרים את מערכי הנתונים החיצוניים באמצעות חיבור CLOUD_RESOURCE, צריך את ההרשאה bigquery.connections.delegate (זמינה בתפקיד אדמין של חיבורי BigQuery) בחיבור שבו משתמשים מערכי הנתונים החיצוניים.

יצירת תצוגה מהותית לא מצטברת על סמך טבלאות ממערך נתונים חיצוני

לפני שממשיכים, צריך ליצור את מערך הנתונים החיצוני הבסיסי של Spanner באמצעות חיבור CLOUD_RESOURCE.

אתם יכולים ליצור תצוגות מהותיות לא מצטברות שמפנות לטבלאות של מערכי נתונים חיצוניים ב-Spanner באמצעות האפשרות allow_non_incremental_definition. בדוגמה הבאה נעשה שימוש בטבלה בסיסית של מערך נתונים חיצוני ב-Spanner:

/*
  You must create the spanner_external_dataset with a CLOUD_RESOURCE connection.
*/
CREATE MATERIALIZED VIEW sample_dataset.sample_spanner_mv
  OPTIONS (
      enable_refresh = true, refresh_interval_minutes = 60,
      max_staleness = INTERVAL "24" HOUR,
        allow_non_incremental_definition = true)
AS
  SELECT COUNT(*) cnt FROM spanner_external_dataset.spanner_table;

רק תצוגות מהותיות לא מצטברות של BigQuery יכולות לכלול טבלאות של מערכי נתונים חיצוניים של Spanner כמסדי נתונים טבלאיים. אם הרענון האחרון של תצוגה מהותית לא מצטברת התרחש מחוץ למרווח הזמן של max_staleness, השאילתה קוראת את הטבלאות של מערך הנתונים החיצוני הבסיסי של Spanner. מידע נוסף על תצוגות מהותיות לא מצטברות ב-BigQuery

המאמרים הבאים

• מידע ולמידה על Data Boost ב-סקירה כללית על Data Boost
• שימוש ב-Data Boost באפליקציות
• מעקב אחרי השימוש ב-Data Boost
• מעקב וניהול של השימוש במכסות של Data Boost
• מידע נוסף על מערך נתונים חיצוני של Spanner
• מידע נוסף על יצירת תצוגות מהותיות על מערכי נתונים חיצוניים של Spanner