ייצוא נתונים ל-Spanner (העברת נתונים הפוכה של ETL)

במאמר הזה מוסבר איך מגדירים תהליך עבודה של חילוץ, טרנספורמציה וטעינה הפוכים (ETL הפוך) מ-BigQuery ל-Spanner. כדי לעשות את זה, אתם יכולים להשתמש בהצהרה EXPORT DATA כדי לייצא נתונים ממקורות נתונים של BigQuery, כולל טבלאות Iceberg, לטבלה של Spanner.

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

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

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

• להקצות תפקידים בניהול זהויות והרשאות גישה (IAM) שנותנים למשתמשים את ההרשאות הנדרשות לביצוע כל משימה במסמך הזה.

• כדי להשתמש בתכונה הזו, צריך ליצור הזמנה של BigQuery ברמת Enterprise או Enterprise Plus. לייצוא באצווה נדרשת הקצאה של QUERY, ולייצוא רציף נדרשת הקצאה של CONTINUOUS.

כדי להפחית את עלויות המחשוב ב-BigQuery כשמריצים ייצוא חד-פעמי ל-Spanner, אפשר להגדיר את קיבולת הבסיס של ה-slots ל-0 ולהפעיל התאמה לעומס (autoscaling).

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לייצוא נתונים מ-BigQuery ל-Spanner, בקשו מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

• ייצוא נתונים מטבלה ב-BigQuery: צפייה בנתוני BigQuery (roles/bigquery.dataViewer)
• הפעלת משימת חילוץ: משתמש BigQuery (roles/bigquery.user)
• בודקים את הפרמטרים של המכונה ב-Spanner: צפייה ב-Cloud Spanner ‏ (roles/spanner.viewer)
• כתיבת נתונים בטבלה של Spanner: משתמש במסד הנתונים של Cloud Spanner (roles/spanner.databaseUser)

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

מגבלות

• התכונה הזו לא נתמכת ב-Assured Workloads.

• סוגי הנתונים הבאים של BigQuery לא נתמכים ב-Spanner ואין להם מקבילות:

• הגודל המקסימלי של שורה שאפשר לייצא הוא 1 MiB.

• במהלך הייצוא, Spanner אוכף את שלמות ההפניות. אם טבלת היעד היא צאצא של טבלה אחרת (INTERLEAVE IN PARENT), או אם יש בטבלת היעד אילוצים של מפתחות זרים, המפתחות הזרים ומפתח ההורה יאומתו במהלך הייצוא. אם שורה מיוצאת נכתבת בטבלה עם INTERLEAVE IN PARENT ושורת ההורה לא קיימת, הייצוא ייכשל עם השגיאה "Parent row is missing. לא ניתן לכתוב את השורה". אם השורה המיוצאת נכתבת בטבלה עם אילוצי מפתח זר והיא מפנה למפתח שלא קיים, הייצוא ייכשל ותופיע השגיאה "Foreign key constraint is violated". כשמייצאים למספר טבלאות, מומלץ לייצא אותן ברצף כדי לשמור על שלמות הייחוס במהלך הייצוא. בדרך כלל זה אומר לייצא טבלאות הורה וטבלאות שמפנים אליהן באמצעות מפתחות זרים לפני הטבלאות שמפנות אליהן.

  אם בטבלה שמייצאים אליה יש אילוצים של מפתחות זרים, או שהיא צאצא של טבלה אחרת (INTERLEAVE IN PARENT), צריך לאכלס את טבלת ההורה לפני שמייצאים את טבלת הצאצא, והיא צריכה להכיל את כל המפתחות התואמים. ניסיון לייצא טבלת צאצא בזמן שבטבלת הורה אין את קבוצת המפתחות הרלוונטיים המלאה ייכשל.

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

• אפשר לייצא ל-Spanner רק במהדורות BigQuery Enterprise או Enterprise Plus. אין תמיכה במהדורת BigQuery Standard ובמחשוב על פי דרישה.

• אי אפשר להשתמש בשאילתות מתמשכות כדי לייצא לטבלאות Spanner עם מפתחות ראשיים שנוצרו אוטומטית.

• אי אפשר להשתמש בשאילתות מתמשכות כדי לייצא לטבלאות Spanner במסד נתונים עם ניב PostgreSQL.

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

הגדרת ייצוא עם האפשרות spanner_options

אתם יכולים להשתמש באפשרות spanner_options כדי לציין מסד נתונים וטבלה של Spanner כיעד. ההגדרה מבוטאת בצורה של מחרוזת JSON, כמו בדוגמה הבאה:

EXPORT DATA OPTIONS(
   uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
   spanner_options = """{
      "table": "TABLE_NAME",
      "change_timestamp_column": "CHANGE_TIMESTAMP",
      "priority": "PRIORITY",
      "tag": "TAG",
   }"""
)

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

• ‫PROJECT_ID: שם הפרויקט ב- Cloud de Confiance .
• ‫INSTANCE_ID: השם של המכונה של מסד הנתונים.
• ‫DATABASE_ID: שם מסד הנתונים.
• ‫TABLE_NAME: השם של טבלת יעדים קיימת.
• ‫CHANGE_TIMESTAMP: השם של העמודה מסוג מוגדר TIMESTAMP בטבלת היעד ב-Spanner. האפשרות הזו משמשת במהלך הייצוא כדי לעקוב אחרי חותמת הזמן של עדכון השורה האחרון. כשמציינים את האפשרות הזו, הייצוא קורא קודם את השורה בטבלת Spanner כדי לוודא שרק העדכון האחרון של השורה נכתב. מומלץ לציין עמודה מסוג מוגדר TIMESTAMP כשמפעילים ייצוא רציף, שבו חשוב הסדר של השינויים בשורות עם אותו מפתח ראשי.
• ‫PRIORITY (אופציונלי): העדיפות של בקשות הכתיבה. ערכים מותרים: LOW, ‏ MEDIUM, ‏ HIGH. ערך ברירת המחדל: MEDIUM.
• TAG (אופציונלי): תג בקשה כדי לזהות את תנועת הייצוא במעקב של Spanner. ערך ברירת המחדל: bq_export.

דרישות לגבי שאילתת הייצוא

כדי לייצא תוצאות של שאילתות ל-Spanner, התוצאות צריכות לעמוד בדרישות הבאות:

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

המרות סוגים

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

ייצוא נתונים

אתם יכולים להשתמש בהצהרת EXPORT DATA כדי לייצא נתונים מטבלה ב-BigQuery לטבלה ב-Spanner.

בדוגמה הבאה, מייצאים שדות נבחרים מטבלה בשם mydataset.table1:

EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME" }"""
)
AS SELECT * FROM mydataset.table1;

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

• ‫PROJECT_ID: שם הפרויקט ב- Cloud de Confiance
• ‫INSTANCE_ID: השם של המכונה של מסד הנתונים
• ‫DATABASE_ID: השם של מסד הנתונים
• ‫TABLE_NAME: השם של טבלת יעד קיימת

ייצוא של כמה תוצאות עם אותו ערך rowkey

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

ייצוא באמצעות חיבור ל-CLOUD_RESOURCE

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

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

יצירת חיבור

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

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}")

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

# 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 {}
}

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

הגדרת גישה

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

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

1. נכנסים לדף Spanner instances.

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

2. לוחצים על השם של המכונה שמכילה את מסד הנתונים.

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

4. מופיעה תיבת הדו-שיח Info panel. לוחצים על Add principal.

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

6. בשדה Select a role, בוחרים תפקיד עם הרשאות spanner.databases.write. מומלץ להשתמש בתפקיד משתמש במסד נתונים ב-Cloud Spanner.

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

מפעילים את הייצוא באמצעות החיבור של CLOUD_RESOURCE

אחרי שיוצרים את החיבור ומעניקים לו את הרשאות הגישה המתאימות, אפשר להריץ את הייצוא באמצעות החיבור CLOUD_RESOURCE. בדוגמה הבאה מוצגת פקודת EXPORT שמייצאת באמצעות חיבור CLOUD_RESOURCE.

EXPORT DATA WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME` OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "SPANNER_TABLE_NAME" }"""
)
AS SELECT * FROM my_bq_dataset.table1;

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

• ‫PROJECT_ID: שם הפרויקט ב- Cloud de Confiance .
• ‫LOCATION: המיקום שבו יצרתם את החיבור, לדוגמה us.
• ‫CONNECTION_NAME: שם החיבור שמשמש להפעלת הייצוא, לדוגמה myconnection.
• ‫INSTANCE_ID: השם של המכונה של מסד הנתונים ב-Spanner.
• ‫DATABASE_ID: השם של מסד הנתונים ב-Spanner.
• ‫SPANNER_TABLE_NAME: השם של טבלת היעד הקיימת ב-Spanner.

ייצוא רציף

כדי לעבד באופן רציף שאילתת ייצוא, קראו את ההוראות ליצירת שאילתות מתמשכות ואת הקוד לדוגמה.

אופטימיזציה של הייצוא

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

• מגדילים את מספר הצמתים במכונה של Spanner ביעד. בשלבים המוקדמים של הייצוא, יכול להיות שהגדלת מספר הצמתים במכונה לא תגדיל באופן מיידי את קצב העברת הנתונים של הייצוא. יכול להיות שיהיה עיכוב קל בזמן ש-Spanner מבצע פיצול מבוסס-עומס. בפיצול מבוסס-עומס, קצב העברת הנתונים של הייצוא גדל ומתייצב. השימוש בהצהרה EXPORT DATA מאפשר לאסוף נתונים באצוות כדי לבצע אופטימיזציה של פעולות הכתיבה ב-Spanner. מידע נוסף זמין במאמר סקירה כללית של הביצועים.

• צריך לציין את העדיפות של HIGH בתוך spanner_options. אם במכונה של Spanner מופעלת התאמה אוטומטית לעומס (scaling), הגדרת עדיפות HIGH עוזרת להבטיח שניצול ה-CPU יגיע לסף הנדרש כדי להפעיל את ההתאמה לעומס. כך, המנגנון להתאמה אוטומטית לעומס יכול להוסיף משאבי מחשוב בתגובה לעומס הייצוא, מה שיכול לשפר את תפוקת הייצוא הכוללת.

  בדוגמה הבאה מוצגת פקודת ייצוא של Spanner שמוגדרת לעדיפות HIGH:

  EXPORT DATA OPTIONS (
    uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    format='CLOUD_SPANNER',
    spanner_options="""{ "table": "TABLE_NAME", "priority": "LOW" }"""
  )

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

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

  לדוגמה, בסכימה הבאה של Spanner, ‏ SaleYear ו-SaleMonth הן עמודות שנוצרו ומרכיבות את תחילת המפתח הראשי של Spanner:

  CREATE TABLE Sales (
    SaleId STRING(36) NOT NULL,
    ProductId INT64 NOT NULL,
    SaleTimestamp TIMESTAMP NOT NULL,
    Amount FLOAT64,
    -- Generated columns
    SaleYear INT64 AS (EXTRACT(YEAR FROM SaleTimestamp)) STORED,
    SaleMonth INT64 AS (EXTRACT(MONTH FROM SaleTimestamp)) STORED,
  ) PRIMARY KEY (SaleYear, SaleMonth, SaleId);

  כשמייצאים נתונים מ-BigQuery לטבלה ב-Spanner עם עמודות שנוצרו ומשמשות כמפתח הראשי, מומלץ (אבל לא חובה) לכלול את הביטויים של העמודות האלה בשאילתת EXPORT DATA. כך BigQuery יכול למיין מראש את הנתונים בצורה נכונה, וזה קריטי כדי ליצור אצוות ולכתוב ל-Spanner בצורה יעילה. הערכים של העמודות שנוצרו בהצהרת EXPORT DATA לא נשמרים ב-Spanner, כי הם נוצרים אוטומטית על ידי Spanner, אבל הם משמשים לאופטימיזציה של הייצוא.

  בדוגמה הבאה מייצאים נתונים לטבלת Spanner Sales שהמפתח הראשי שלה משתמש בעמודות שנוצרו. כדי לשפר את ביצועי הכתיבה, השאילתה כוללת ביטויי EXTRACT שתואמים לעמודות SaleYear ו-SaleMonth שנוצרו, וכך BigQuery יכול למיין מראש את הנתונים לפני הייצוא:

  EXPORT DATA OPTIONS (
    uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    format='CLOUD_SPANNER',
    spanner_options="""{ "table": "Sales" }"""
  )
  AS SELECT
    s.SaleId,
    s.ProductId,
    s.SaleTimestamp,
    s.Amount,
    -- Add expressions that match the generated columns in the Spanner PK
    EXTRACT(YEAR FROM s.SaleTimestamp) AS SaleYear,
    EXTRACT(MONTH FROM s.SaleTimestamp) AS SaleMonth
  FROM my_dataset.sales_export AS s;

• כדי למנוע משימות ארוכות, כדאי לייצא נתונים לפי מחיצה. מפצלים את הנתונים ב-BigQuery באמצעות מפתח חלוקה, כמו חותמת זמן בשאילתה:

  EXPORT DATA OPTIONS (
    uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    format='CLOUD_SPANNER',
    spanner_options="""{ "table": "TABLE_NAME", "priority": "MEDIUM" }"""
  )
  AS SELECT *
  FROM 'mydataset.table1' d
  WHERE
  d.timestamp >= TIMESTAMP '2025-08-28T00:00:00Z' AND
  d.timestamp < TIMESTAMP '2025-08-29T00:00:00Z';

  כך השאילתה תוכל להסתיים במסגרת זמן הריצה של המשימה, שנמשך 6 שעות. מידע נוסף על המגבלות האלה זמין במאמר מגבלות על משימות של שאילתות.

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

• מומלץ להתחיל עם צומת Spanner אחד (1,000 יחידות עיבוד) והזמנה מינימלית של יחידות קיבולת של BigQuery. לדוגמה, 100 משבצות או 0 משבצות בסיסיות עם התאמה אוטומטית לעומס. בייצוא של פחות מ-100GB, ההגדרה הזו בדרך כלל מסתיימת במסגרת מגבלת הזמן של 6 שעות. בייצוא של יותר מ-100GB, מגדילים את קצב העברת הנתונים על ידי הגדלת מספר הצמתים ב-Spanner והזמנת יחידות קיבולת של BigQuery, לפי הצורך. קצב העברת הנתונים הוא בערך 5MiB לשנייה לכל צומת.

תמחור

כשמייצאים נתונים ל-Spanner באמצעות ההצהרה EXPORT DATA, החיוב מתבצע לפי תמחור המחשוב של קיבולת BigQuery.

כדי לייצא באופן רציף ל-Spanner באמצעות שאילתה רציפה, צריך להקצות מקום שמור ליחידות קיבולת (slot) במהדורת BigQuery Enterprise או Enterprise Plus, ולהקצות מקום שמור שמשתמש בסוג המשימה CONTINUOUS.

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

אחרי שהנתונים מיוצאים, אתם מחויבים על אחסון הנתונים ב-Spanner. למידע נוסף, ראו התמחור של Spanner.