הרצת שאילתות מאוחדות באמצעות 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, צריך לבצע את המשימות הבאות:

יוצרים מסד נתונים ומופע Spanner.
מפעילים את BigQuery Connection API.
הענקת הרשאות ה-IAM הנדרשות.

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

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

הפעלת BigQuery Connection API

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

Enable the BigQuery connection API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the 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:

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

הפעלת שאילתת Data Boost ב-Spanner

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

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

כניסה לדף Instances

במסוף מוצגת רשימה של מופעי Spanner.
בוחרים מופע Spanner ואז בוחרים מסד נתונים.
בדף Database overview (סקירה כללית של מסד הנתונים), בתפריט הניווט, לוחצים על Spanner Studio.
לוחצים על הצגה ב-BigQuery.
בתיבת הדו-שיח View in BigQuery (הצגה ב-BigQuery), מזינים מזהה חיבור.

מזהה החיבור משמש ליצירת חיבור חיצוני חדש ל-BigQuery למסד הנתונים של Spanner. אתם מפנים לחיבור החיצוני באמצעות התבנית הבאה:
```
PROJECT-ID.LOCATION.CONNECTION-ID
```
אם המזהה כבר קיים, תופיע שגיאה.
ממלאים את שאר הפרטים בתיבת הדו-שיח ומבצעים את הפעולות הבאות:
- בוחרים באפשרות קריאת נתונים במקביל.
- בוחרים באפשרות Use Spanner Data Boost (שימוש ב-Spanner Data Boost).
לוחצים על הצגה ב-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, בוחרים באחת מהאפשרויות הבאות:

המסוף

עוברים אל יצירת חיבורים ל-Spanner במסמכי BigQuery ופועלים לפי ההוראות בכרטיסייה Console.
בחלונית External data source:
- בוחרים באפשרות קריאת נתונים במקביל.
- בוחרים באפשרות Use Spanner Data Boost (שימוש ב-Spanner Data Boost).

BQ

עוברים אל יצירת חיבורים ל-Spanner במאמרי העזרה של BigQuery ופועלים לפי ההוראות בכרטיסייה bq*.
מגדירים את מאפייני החיבור הבאים לערך 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 הבסיסיות. חיבור למשאב ב-Cloud שמשויך לחשבון שירות משמש לחיבור ל-Spanner. משתמשים יכולים להריץ שאילתות בטבלאות Spanner האלה מתוך מערכי נתונים חיצוניים, גם אם לא הוענקה להם גישה ב-Spanner.

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

יצירת חיבור

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

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

המסוף

עוברים לדף BigQuery.

כניסה ל-BigQuery
בחלונית השמאלית, לוחצים על Explorer:

אם החלונית הימנית לא מוצגת, לוחצים על הרחבת החלונית הימנית כדי לפתוח אותה.
בחלונית Explorer מרחיבים את שם הפרויקט ואז לוחצים על Connections.
בדף Connections (חיבורים), לוחצים על Create connection (יצירת חיבור).
בקטע Connection type (סוג החיבור), בוחרים באפשרות Vertex AI remote models, remote functions, BigLake and Spanner (Cloud Resource) (מודלים מרוחקים של Vertex AI, פונקציות מרוחקות, BigLake ו-Spanner (משאב בענן)).
בשדה מזהה החיבור, מזינים שם לחיבור.
בקטע Location type, בוחרים מיקום לחיבור. החיבור צריך להיות ממוקם יחד עם המשאבים האחרים שלכם, כמו מערכי נתונים.
לוחצים על יצירת קישור.
לוחצים על מעבר לחיבור.
בחלונית Connection info (פרטי התחברות), מעתיקים את מזהה חשבון השירות כדי להשתמש בו בשלב מאוחר יותר.

BQ

בסביבת שורת פקודה, יוצרים חיבור:
```
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...
```

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

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

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

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

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}`);
    }
  }
}

Terraform

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

כדי לבצע אימות ב-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

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

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

הכנת הספרייה

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

יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

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

לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.
בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
שומרים את השינויים.
מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.
```
terraform init
```
אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:
```
terraform init -upgrade
```

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

בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:
```
terraform plan
```
מתקנים את ההגדרות לפי הצורך.
מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:
```
terraform apply
```
ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".
פותחים את Google Cloud הפרויקט כדי לראות את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

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

אישור הגישה

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

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

עוברים לדף Instances (מופעים) ב-Spanner.

כניסה לדף Instances
לוחצים על שם המופע שמכיל את מסד הנתונים כדי לעבור לדף פרטי המופע.
בכרטיסייה סקירה כללית, מסמנים את תיבת הסימון של מסד הנתונים.
חלונית המידע מופיעה.
לוחצים על Add principal.
בחלונית Add principals, בשדה New principals, מזינים את המזהה של חשבון השירות שהעתקתם קודם.
בשדה Select a role, בוחרים באפשרות Cloud Spanner Database Reader with DataBoost role.
לוחצים על Save.

יצירה של קבוצת נתונים חיצונית

כדי ליצור מערך נתונים חיצוני:

המסוף

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

לדף BigQuery
בחלונית הימנית, לוחצים על כלי הניתוחים:

אם החלונית הימנית לא מוצגת, לוחצים על הרחבת החלונית הימנית כדי לפתוח אותה.
בחלונית Explorer, בוחרים את הפרויקט שבו רוצים ליצור את מערך הנתונים.
לוחצים על View actions (הצגת פעולות) ואז על Create dataset (יצירת מערך נתונים).
בדף 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
  - אופציונלי: מסמנים את התיבה לצד שימוש בחיבור למשאב בענן כדי ליצור את מערך הנתונים החיצוני עם חיבור.
- משאירים את שאר הגדרות ברירת המחדל כמו שהן.
לוחצים על יצירת מערך נתונים.

SQL

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

במסוף Google Cloud , עוברים לדף BigQuery.

כניסה ל-BigQuery
מזינים את ההצהרה הבאה בעורך השאילתות:
```
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.
לוחצים על הפעלה.

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

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, צריך להגדיר את 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

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

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

הכנת הספרייה

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

יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

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

לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.
בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
שומרים את השינויים.
מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.
```
terraform init
```
אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:
```
terraform init -upgrade
```

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

בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:
```
terraform plan
```
מתקנים את ההגדרות לפי הצורך.
מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:
```
terraform apply
```
ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".
פותחים את Google Cloud הפרויקט כדי לראות את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

API

קוראים לשיטה datasets.insert עם משאב של מערך נתונים מוגדר ועם השדה externalDatasetReference במסד הנתונים של Spanner.

שימו לב: השמות של הטבלאות במערכי הנתונים החיצוניים לא תלויי-רישיות (case-insensitive).

כשיוצרים מערכי נתונים חיצוניים באמצעות 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 קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

הפעלת BigQuery Connection API

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

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

הפעלת שאילתת Data Boost ב-Spanner

איך מתחילים ב-BigQuery כדי להריץ שאילתה של Data Boost

המסוף

BQ

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

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

יצירת חיבור

המסוף

BQ

Python

Node.js

Terraform

הכנת Cloud Shell

הכנת הספרייה

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

אישור הגישה

יצירה של קבוצת נתונים חיצונית

המסוף

SQL

BQ

Terraform

הכנת Cloud Shell

הכנת הספרייה

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

API

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

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

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

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