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

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

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

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

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

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

• יוצרים בקשה לשמירת מקום ברמת Enterprise או ברמה גבוהה יותר. כדי להקטין את עלויות החישוב ב-BigQuery כשמריצים ייצוא חד-פעמי ל-Spanner, אפשר להגדיר קיבולת בסיסית של יחידות קיבולת (Slot) לאפס ולהפעיל התאמה אוטומטית לעומס (automatic scaling).

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

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

• ייצוא נתונים מטבלה ב-BigQuery: BigQuery Data Viewer (roles/bigquery.dataViewer)
• הפעלת משימת חילוץ: BigQuery User (roles/bigquery.user)
• בודקים את הפרמטרים של מכונת Spanner: Cloud Spanner Viewer (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 (שורת ההורה חסרה). השגיאה 'אי אפשר לכתוב את השורה'. אם השורה המיוצאת נכתבת לטבלה עם אילוצי מפתח זר והיא מפנה למפתח שלא קיים, הייצוא ייכשל עם השגיאה 'הפרה של אילוץ מפתח זר'. כשמייצאים לכמה טבלאות, מומלץ להגדיר את רצף הייצוא כדי לוודא שהשלמות ההפניה תישמר במהלך הייצוא. בדרך כלל צריך לייצא טבלאות אב וטבלאות שמפנות למפתחות זרים לפני טבלאות שמפנות אליהן.

  אם הטבלה שאליה מייצאים נתונים כוללת אילוצים של מפתח זר, או שהיא צאצא של טבלה אחרת (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 type כשמריצים ייצוא רציף, שבו סדר השינויים בשורות עם אותו מפתח ראשי חשוב.
• ‫PRIORITY (אופציונלי): 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, צריך לבצע את הפעולות הבאות:

יצירת חיבור

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

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 Database User (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, הגדרת העדיפות HIGH עוזרת להבטיח שהשימוש במעבד יגיע לסף הנדרש להפעלת ההתאמה לעומס. כך, הכלי לשינוי קנה מידה אוטומטי יכול להוסיף משאבי מחשוב בתגובה לעומס הייצוא, מה שיכול לשפר את התפוקה הכוללת של הייצוא.

  בדוגמה הבאה מוצגת פקודת ייצוא של 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, אבל הם משמשים לאופטימיזציה של הייצוא.

  בדוגמה הבאה מיוצאים נתונים לטבלת Sales ב-Spanner, שבה המפתח הראשי משתמש בעמודות שנוצרו. כדי לייעל את ביצועי הכתיבה, השאילתה כוללת ביטויים של 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 יחידות קיבולת בסיסיות עם התאמה אוטומטית לעומס. בדרך כלל, ייצואים של עד 100 GB מסתיימים תוך 6 שעות, שהוא הזמן המקסימלי שמוגדר לעבודות. כדי לייצא נתונים בנפח של יותר מ-100GB, צריך להגדיל את קצב העברת הנתונים על ידי הרחבת הצמתים של Spanner והזמנת יחידות קיבולת של BigQuery, לפי הצורך. התפוקה גדלה בערך ב-5 MiB/s לכל צומת.

תמחור

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

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

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

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