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

הערה: לתרגומים מבוססי API, כולל תרגומים חדשים של קבוצות, מומלץ להשתמש ב-BigQuery Migration API כדי לתרגם את סקריפטים ה-SQL. ‫BigQuery Migration API פועל בדומה למתרגם SQL של קבוצות, אבל בלי הצורך להתקין או להשתמש בקוד לקוח.

במאמר הזה מוסבר איך להשתמש בכלי לתרגום קבוצתי של SQL ב-BigQuery כדי לתרגם סקריפטים שנכתבו בניבים אחרים של SQL לשאילתות GoogleSQL. המסמך הזה מיועד למשתמשים שמכירים את מסוףGoogle Cloud .

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

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

1. מוודאים שיש לכם את כל ההרשאות הנדרשות.
2. מפעילים את BigQuery Migration API.
3. אוספים את קובצי המקור שמכילים את הסקריפטים והשאילתות של SQL שרוצים לתרגם.
4. זה שינוי אופציונלי. יוצרים קובץ מטא-נתונים כדי לשפר את דיוק התרגום.
5. זה שינוי אופציונלי. מחליטים אם צריך למפות שמות של אובייקטים ב-SQL בקובצי המקור לשמות חדשים ב-BigQuery. אם צריך, קובעים אילו כללי מיפוי שמות יש להשתמש בהם.
6. קובעים באיזו שיטה להשתמש כדי לשלוח את עבודת התרגום.
7. מעלים את קובצי המקור ל-Cloud Storage.

ההרשאות הנדרשות

כדי להפעיל את שירות ההעברה של BigQuery, צריך לקבל את ההרשאות הבאות בפרויקט:

• resourcemanager.projects.get
• serviceusage.services.enable
• serviceusage.services.get

כדי לגשת אל BigQuery Migration Service ולהשתמש בו, אתם צריכים את ההרשאות הבאות בפרויקט:

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get
• bigquerymigration.workflows.list
• bigquerymigration.workflows.delete
• bigquerymigration.subtasks.get

• bigquerymigration.subtasks.list

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

  • bigquerymigration.viewer - הרשאת קריאה בלבד.
  • ‫bigquerymigration.editor - גישת קריאה/כתיבה.

כדי לגשת לקטגוריות של Cloud Storage עבור קובצי קלט ופלט:

• ‫storage.objects.get בקטגוריית המקור של Cloud Storage.
• ‫storage.objects.list בקטגוריית המקור של Cloud Storage.
• ‫storage.objects.create בקטגוריית היעד של Cloud Storage.

התפקידים הבאים כוללים את כל ההרשאות הנדרשות ל-Cloud Storage שצוינו למעלה:

• roles/storage.objectAdmin
• roles/storage.admin

הפעלת BigQuery Migration API

אם הפרויקט שלכם ב-Google Cloud CLI נוצר לפני 15 בפברואר 2022, צריך להפעיל את BigQuery Migration API באופן הבא:

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

   מעבר אל BigQuery Migration API

2. לוחצים על Enable.

הערה: בפרויקטים שנוצרו אחרי 15 בפברואר 2022, ה-API הזה מופעל באופן אוטומטי.

איסוף קובצי מקור

קובצי המקור צריכים להיות קובצי טקסט שמכילים SQL תקין בניב המקור. קובצי המקור יכולים לכלול גם הערות. כדאי לעשות כמיטב היכולת כדי לוודא ש-SQL תקין, באמצעות כל השיטות שזמינות לכם.

יצירת קובצי מטא-נתונים

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

אפשר להשתמש בכלי החילוץ של שורת הפקודה dwh-migration-dumper כדי ליצור את נתוני המטא-נתונים, או לספק קובצי מטא-נתונים משלכם. אחרי שמכינים את קובצי המטא-נתונים, אפשר לכלול אותם יחד עם קובצי המקור בתיקיית המקור של התרגום. הכלי לתרגום מזהה אותם באופן אוטומטי ומשתמש בהם כדי לתרגם קובצי מקור, כך שלא צריך להגדיר הגדרות נוספות כדי להפעיל את התכונה הזו.

כדי ליצור מידע על מטא-נתונים באמצעות הכלי dwh-migration-dumper, ראו יצירת מטא-נתונים לתרגום.

כדי לספק מטא-נתונים משלכם, צריך לאסוף את הצהרות שפת הגדרת הנתונים (DDL) של אובייקטי ה-SQL במערכת המקור בקובצי טקסט נפרדים.

החלטה איך לשלוח את עבודת התרגום

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

• לקוח לתרגום באצווה: מגדירים משימה על ידי שינוי ההגדרות בקובץ תצורה, ושולחים את המשימה באמצעות שורת הפקודה. בגישה הזו לא צריך להעלות ידנית קובצי מקור ל-Cloud Storage. הלקוח עדיין משתמש ב-Cloud Storage כדי לאחסן קבצים במהלך עיבוד משימת התרגום.

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

• Google Cloud מסוף: הגדרה ושליחה של משימה באמצעות ממשק משתמש. בגישה הזו צריך להעלות קובצי מקור ל-Cloud Storage.

יצירת קובצי YAML של תצורה

אפשר גם ליצור ולהשתמש בקבצי YAML של הגדרות כדי להתאים אישית את התרגומים של קבוצות קבצים. אפשר להשתמש בקבצים האלה כדי לשנות את פלט התרגום בדרכים שונות. לדוגמה, אפשר ליצור קובץ תצורה מסוג YAML כדי לשנות את האותיות של אובייקט SQL במהלך התרגום.

אם רוצים להשתמש במסוף Google Cloud או ב-BigQuery Migration API כדי להריץ תרגום באצווה, אפשר להעלות את קובץ ה-YAML של ההגדרות לקטגוריה של Cloud Storage שמכילה את קובצי המקור.

אם רוצים להשתמש בלקוח של תרגום באצווה, אפשר למקם את קובץ ה-YAML של ההגדרה בתיקיית הקלט המקומית של התרגום.

העלאת קובצי קלט ל-Cloud Storage

אם רוצים להשתמש במסוף Google Cloud או ב-BigQuery Migration API כדי לבצע עבודת תרגום, צריך להעלות ל-Cloud Storage את קובצי המקור שמכילים את השאילתות והסקריפטים שרוצים לתרגם. אפשר גם להעלות קובצי מטא-נתונים או קובצי YAML של הגדרות לאותה קטגוריה של Cloud Storage ולאותה ספרייה שמכילות את קובצי המקור. מידע נוסף על יצירת קטגוריות והעלאת קבצים ל-Cloud Storage זמין במאמרים בנושא יצירת קטגוריות והעלאת אובייקטים ממערכת קבצים.

דיאלקטים נתמכים של SQL

כלי התרגום של SQL בקבוצות הוא חלק משירות ההעברה ל-BigQuery. הכלי לתרגום SQL באצווה יכול לתרגם את הדיאלקטים הבאים של SQL ל-GoogleSQL:

• Amazon Redshift SQL
• ‫Apache HiveQL ו-Beeline CLI
• ‫IBM Netezza SQL ו-NZPLSQL
• ‫Teradata ו-Teradata Vantage:
  • SQL
  • שאילתת Teradata בסיסית (BTEQ)
  • ‫Teradata Parallel Transport‏ (TPT)

בנוסף, יש תמיכה בתרגום של הדיאלקטים הבאים של SQL בגרסת טרום-השקה:

• ‫Apache Impala SQL
• Apache Spark SQL
• Azure Synapse T-SQL
• ‫GoogleSQL (BigQuery)
• Greenplum SQL
• IBM DB2 SQL
• MySQL SQL
• Oracle SQL, ‏ PL/SQL, ‏ Exadata
• ‫PostgreSQL SQL
• ‫Trino או PrestoSQL
• ‫Snowflake SQL
• SQL Server T-SQL
• SQLite
• Vertica SQL

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

טיפול בפונקציות SQL שלא נתמכות באמצעות פונקציות UDF מסייעות

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

פונקציות UDF כאלה נמצאות לרוב במערך הנתונים הציבורי bqutil, כך ששאילתות מתורגמות יכולות להפנות אליהן בהתחלה באמצעות הפורמט bqutil.<dataset>.<function>(). לדוגמה, bqutil.fn.cw_count().

שיקולים חשובים לגבי סביבות ייצור:

למרות ש-bqutil מספק גישה נוחה לפונקציות העזר האלה של UDF לצורך תרגום ובדיקה ראשוניים, לא מומלץ להסתמך ישירות על bqutil לעומסי עבודה של ייצור מכמה סיבות:

1. ניהול גרסאות: פרויקט bqutil מארח את הגרסה העדכנית של הפונקציות האלה, כלומר ההגדרות שלהן יכולות להשתנות לאורך זמן. הסתמכות ישירה על bqutil עלולה להוביל להתנהגות בלתי צפויה או לשינויים שוברים בשאילתות הייצור שלכם אם הלוגיקה של UDF מתעדכנת.
2. בידוד תלות: פריסת פונקציות UDF בפרויקט שלכם מבודדת את סביבת הייצור משינויים חיצוניים.
3. התאמה אישית: יכול להיות שתצטרכו לשנות או לבצע אופטימיזציה של הפונקציות המוגדרות על ידי המשתמש כדי שיתאימו יותר ללוגיקה העסקית הספציפית או לדרישות הביצועים שלכם. הפעולה הזו אפשרית רק אם הם נמצאים בפרויקט שלכם.
4. אבטחה וניהול: יכול להיות שמדיניות האבטחה של הארגון שלכם מגבילה גישה ישירה למערכי נתונים ציבוריים כמו bqutil לעיבוד נתוני ייצור. העתקת פונקציות UDF לסביבה המבוקרת שלכם תואמת למדיניות כזו.

פריסת פונקציות UDF מסוג helper בפרויקט:

כדי להשתמש בפונקציות העזר האלה בייצור בצורה מהימנה ויציבה, צריך לפרוס אותן בפרויקט ובמערך הנתונים שלכם. כך יש לכם שליטה מלאה בגרסה, בהתאמה האישית ובגישה שלהם. הוראות מפורטות להטמעה של פונקציות UDF זמינות במדריך להטמעה של פונקציות UDF ב-GitHub. במדריך הזה מפורטים הסקריפטים והשלבים שנדרשים כדי להעתיק את הפונקציות המוגדרות על ידי המשתמש לסביבה שלכם.

מיקומים

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

	תיאור האזור	שם האזור	פרטים
אסיה והאוקיינוס השקט
	דלהי	asia-south2
	הונג קונג	asia-east2
	ג'קארטה	asia-southeast2
	מלבורן	australia-southeast2
	מומבאי	asia-south1
	אוסקה	asia-northeast2
	סיאול	asia-northeast3
	סינגפור	asia-southeast1
	סידני	australia-southeast1
	טייוואן	asia-east1
	טוקיו	asia-northeast1
אירופה
	בלגיה	europe-west1	‫ רמה נמוכה של CO2‎
	ברלין	europe-west10
	מספר אזורים באיחוד האירופי	eu
	פינלנד	europe-north1	‫ רמה נמוכה של CO2‎
	פרנקפורט	europe-west3
	לונדון	europe-west2	‫ רמה נמוכה של CO2‎
	מדריד	europe-southwest1	‫ רמה נמוכה של CO2‎
	מילאנו	europe-west8
	הולנד	europe-west4	‫ רמה נמוכה של CO2‎
	פריז	europe-west9	‫ רמה נמוכה של CO2‎
	שטוקהולם	europe-north2	‫ רמה נמוכה של CO2‎
	טורינו	europe-west12
	ורשה	europe-central2
	ציריך	europe-west6	‫ רמה נמוכה של CO2‎
אמריקה
	קולומבוס, אוהיו	us-east5
	דאלאס	us-south1	‫ רמה נמוכה של CO2‎
	אייווה	us-central1	‫ רמה נמוכה של CO2‎
	לאס וגאס	us-west4
	לוס אנג'לס	us-west2
	מקסיקו	northamerica-south1
	צפון וירג'יניה	us-east4
	אורגון	us-west1	‫ רמה נמוכה של CO2‎
	קוויבק	northamerica-northeast1	‫ רמה נמוכה של CO2‎
	סאו פאולו	southamerica-east1	‫ רמה נמוכה של CO2‎
	סולט לייק סיטי	us-west3
	סנטיאגו	southamerica-west1	‫ רמה נמוכה של CO2‎
	דרום קרוליינה	us-east1
	טורונטו	northamerica-northeast2	‫ רמה נמוכה של CO2‎
	ארה"ב במספר אזורים	us
אפריקה
	יוהנסבורג	africa-south1
MiddleEast
	דמאם	me-central2
	דוחה	me-central1
	ישראל	me-west1

שליחת עבודת תרגום

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

המסוף

אנחנו יוצאים מנקודת הנחה שכבר העליתם קובצי מקור לקטגוריה של Cloud Storage.

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

   מעבר אל SQL Translation

2. בחלונית SQL translation (תרגום SQL), לוחצים על Start translation (התחלת התרגום).

3. בקטע הגדרת תרגום, מזינים את הפרטים הבאים:

   1. בשדה שם התצוגה, מקלידים שם לעבודת התרגום. השם יכול להכיל אותיות, מספרים או קווים תחתונים.
   2. בקטע מיקום העיבוד, בוחרים את המיקום שבו רוצים שהעבודה של התרגום תתבצע. לדוגמה, אם אתם נמצאים באירופה ולא רוצים שהנתונים שלכם יעברו את הגבולות של מיקום כלשהו, אתם יכולים לבחור באזור eu. כדי לקבל את התוצאות הטובות ביותר, מומלץ לבחור את אותו מיקום של דלי קובץ המקור.
   3. בקטע Source dialect (ניב המקור), בוחרים את ניב ה-SQL שרוצים לתרגם.
   4. בקטע ניב היעד, בוחרים באפשרות GoogleSQL.

4. לוחצים על הבא.

5. בקטע פרטים על מיקום הקובץ, מציינים את הנתיבים ב-Cloud Storage שבהם ישתמשו לקלט ולפלט של התרגום. אפשר להקליד את הנתיבים בפורמט bucket_name/folder_name/ או להשתמש באפשרות עיון כדי לנווט לתיקייה.

   1. בקטע מיקום ספריית הפלט, מציינים נתיב לתיקיית היעד ב-Cloud Storage של הקבצים המתורגמים. התיקייה הזו משמשת כתיקיית הבסיס לכל פלט התרגום.
   2. בוחרים מיקום של תיקיית קלט אחת או יותר שמכילה את הנתיב לקובצי ה-SQL שרוצים לתרגם.
   3. אם צריך, אפשר לתת לכל ספריית קלט שם של ספריית משנה לפלט מתחת לספריית הפלט הראשית.

6. לוחצים על הבא.

7. בוחרים את ההגדרות האופציונליות שרוצים להתאים אישית את המטא-נתונים ואת פלט התרגום הנוסף.

8. אפשר להתאים אישית את התנהגות התרגום על ידי יצירת קובצי YAML של הגדרות והצבת הקבצים האלה בקטגוריית הקלט של Cloud Storage. אפשר להשתמש בקבצים האלה כדי להגדיר שינוי שם של אובייקטים, להפעיל אופטימיזציות, לשפר תרגומים באמצעות Gemini ועוד. מידע נוסף על קובצי YAML של הגדרות זמין במאמר יצירת קובץ YAML של הגדרות.

9. לוחצים על יצירה כדי להתחיל את עבודת התרגום.

אחרי שיוצרים את משימת התרגום, אפשר לראות את הסטטוס שלה ברשימת משימות התרגום.

לקוח תרגום באצווה

הערה: מומלץ להשתמש ב-BigQuery Migration API במקום בלקוח של תרגום באצווה לתרגומים חדשים.

1. מתקינים את לקוח התרגום באצווה ואת Google Cloud CLI.

2. יוצרים קובץ פרטי כניסה ל-CLI של gcloud.

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

   • ‫project_number: מקלידים את מספר הפרויקט שבו רוצים להשתמש לעבודת התרגום באצווה. אפשר לראות את זה בחלונית Project info בGoogle Cloud דף הפתיחה של המסוף של הפרויקט.
   • ‫gcs_bucket: מקלידים את השם של קטגוריית Cloud Storage שבה לקוח התרגום באצווה משתמש כדי לאחסן קבצים במהלך העיבוד של עבודת התרגום.
   • ‫input_directory: מקלידים את הנתיב המוחלט או היחסי לספרייה שמכילה את קובצי המקור וקובצי המטא-נתונים.
   • ‫output_directory: מקלידים את הנתיב המוחלט או היחסי לספריית היעד של הקבצים המתורגמים.

4. שומרים את השינויים וסוגרים את הקובץ config.yaml.

5. ממקמים את קובץ המקור ואת קובץ המטא-נתונים בספריית הקלט.

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

   bin/dwh-migration-client
   

7. יוצרים משימת תרגום.

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

     gcloud bq migration-workflows create --location=us --config-file=CONFIG_FILE_NAME.json

   • בדוגמה הבאה מוצגת פקודה ליצירה ולהרצה של תהליך העבודה עם הדגל --async. הפקודה תיצור את תהליך העבודה ותפעיל אותו, ותחזיר מיד קישור לתהליך העבודה.

     gcloud bq migration-workflows create --location=LOCATION  --config-file=CONFIG_FILE_NAME.json --async

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

     gcloud bq migration-workflows list --location=LOCATION

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

   • ‫LOCATION: המיקום של Google Cloud הפרויקט שבו מופעלת משימת התרגום הזו.
   • ‫CONFIG_FILE_NAME: השם של קובץ config.yaml. אחרי שיוצרים את משימת התרגום, אפשר לראות את הסטטוס שלה ברשימת משימות התרגום במסוף Google Cloud .

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

BigQuery CLI

כדי להריץ את כלי התרגום של SQL בקבוצות באמצעות כלי שורת הפקודה של BigQuery, מבצעים את השלבים הבאים:

1. יוצרים קובץ תצורה לתרגום בפורמט YAML או JSON. בקובץ הזה צריך להגדיר את הנתיב לקובץ המקור, את יעד הפלט ואת הניבים של שפת המקור ושפת היעד של התרגום.

   בדוגמה הבאה מוצג קובץ YAML של הגדרות תרגום מ-Teradata ל-BigQuery:

   tasks:
   translation_task:
     type: Teradata2BigQuery_Translation
     translationDetails:
       sourceTargetMapping:
       - sourceSpec:
           baseUri: gs://bq-translations/input
         targetSpec:
           relativePath: output
       targetBaseUri: gs://bq-translations
       targetTypes:
       - sql
       sourceEnvironment:
         defaultDatabase: default_db
         schemaSearchPath:
         - foo

   בדוגמה הבאה מוצג קובץ JSON של הגדרות תרגום מ-Teradata ל-BigQuery:

   {
   "tasks": {
     "translation_task": {
       "type": "Teradata2BigQuery_Translation",
       "translationDetails": {
         "sourceTargetMapping": [
           {
             "sourceSpec": {
               "literal": {
                 "literalString": "sel 1",
                 "relativePath": "my_input_1"
               },
               "encoding": "UTF-8"
             }
           },
           {
             "sourceSpec": {
               "literal": {
                 "literalString": "sel 2",
                 "relativePath": "my_input_2"
               },
               "encoding": "UTF-8"
             }
           }
         ],
         "targetReturnLiterals": [
           "sql/my_input_1",
           "sql/my_input_2"
         ]
       }
     }
   }
   }

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

   bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE_NAME.json

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

   • ‫LOCATION: המיקום של Google Cloud הפרויקט שבו מופעלת משימת התרגום הזו.
   • ‫CONFIG_FILE_NAME: השם של קובץ config.yaml.

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

  bq show --migration_workflow projects/PROJECT_ID/ locations/us/workflows/WORKFLOW_ID

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

  • ‫PROJECT_ID: המזהה של Google Cloud הפרויקט שבו מופעלת משימת התרגום הזו.
  • ‫WORKFLOW_ID: המזהה של עבודת התרגום.

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

  gcloud bq migration-workflows describe projects/PROJECT_ID    /locations/us/workflows/WORKFLOW_ID

• כדי להסיר משימת תרגום מהרשימה, מריצים את הפקודה הבאה:

  bq rm --migration_workflow projects/PROJECT_ID/locations/us/workflows/WORKFLOW_ID

• כדי להציג רשימה של כל עבודות התרגום, מריצים את הפקודה הבאה:

  bq ls --migration_workflow --location=LOCATION

בדיקת פלט התרגום

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

• הקבצים המתורגמים.
• דוח סיכום התרגום בפורמט CSV.
• מיפוי שמות הפלט שנצרך בפורמט JSON.
• הקבצים עם ההצעות מ-AI.

פלט של מסוףGoogle Cloud

כדי לראות את פרטי עבודת התרגום, פועלים לפי השלבים הבאים:

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

   מעבר אל SQL Translation

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

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

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

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

6. לוחצים על הכרטיסייה Job details כדי לראות את פרטי ההגדרה של עבודת התרגום.

דוח סיכום

דוח הסיכום הוא קובץ CSV שמכיל טבלה של כל הודעות האזהרה והשגיאה שנתקלו בהן במהלך עבודת התרגום.

כדי לראות את קובץ הסיכום ב Google Cloud מסוף, פועלים לפי השלבים הבאים:

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

   מעבר אל SQL Translation

2. ברשימת עבודות התרגום, מאתרים את העבודה שרוצים, לוחצים על שם העבודה או על אפשרויות נוספות > הצגת פרטים.

3. בכרטיסייה פרטי המשימה, בקטע דוח תרגום, לוחצים על translation_report.csv.

4. בדף פרטי האובייקט, לוחצים על הערך בשורה כתובת URL מאומתת כדי לראות את הקובץ בדפדפן.

בטבלה הבאה מתוארות העמודות בקובץ הסיכום:

עמודה	תיאור
חותמת הזמן	חותמת הזמן שבה התרחשה הבעיה.
FilePath	הנתיב לקובץ המקור שהבעיה משויכת אליו.
FileName	השם של קובץ המקור שאליו משויכת הבעיה.
ScriptLine	מספר השורה שבה התרחשה הבעיה.
ScriptColumn	מספר העמודה שבה התרחשה הבעיה.
TranspilerComponent	הרכיב הפנימי של מנוע התרגום שבו התרחשה האזהרה או השגיאה. יכול להיות שהעמודה הזו תהיה ריקה.
סביבה	סביבת הדיאלקט של התרגום שמשויכת לאזהרה או לשגיאה. יכול להיות שהעמודה הזו תהיה ריקה.
ObjectName	אובייקט ה-SQL בקובץ המקור שמשויך לאזהרה או לשגיאה. יכול להיות שהעמודה הזו תהיה ריקה.
חוּמרה	חומרת הבעיה, אזהרה או שגיאה.
קטגוריה	קטגוריית הבעיה בתרגום.
SourceType	המקור של הבעיה הזו. הערך בעמודה הזו יכול להיות SQL, שמציין שיש בעיה בקובצי ה-SQL של הקלט, או METADATA, שמציין שיש בעיה בחבילת המטא-נתונים.
הודעה	הודעת האזהרה או השגיאה שקשורה לבעיה בתרגום.
ScriptContext	קטע ה-SQL בקובץ המקור שמשויך לבעיה.
פעולה	הפעולה המומלצת לפתרון הבעיה.

הכרטיסייה 'קוד'

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

כדי לגשת לכרטיסיית הקוד:

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

   מעבר אל SQL Translation

2. ברשימת עבודות התרגום, מאתרים את העבודה שרוצים, לוחצים על שם העבודה או על אפשרויות נוספות > הצגת פרטים.

3. בוחרים באפשרות כרטיסיית קוד. כרטיסיית הקוד מורכבת מהחלוניות הבאות:

   

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

4. אופציונלי: כדי לראות קובץ קלט וקובץ פלט בכלי האינטראקטיבי לתרגום SQL ב-BigQuery, לוחצים על עריכה. אפשר לערוך את הקבצים ולשמור את קובץ הפלט בחזרה ב-Cloud Storage.

הערה: אפשר לראות סיכומים של יומנים והודעות לגבי עבודת התרגום הכוללת בדף התוצאות

הכרטיסייה 'הגדרות'

אפשר להוסיף, לשנות את השם, להציג או לערוך את קובצי ה-YAML של ההגדרות בכרטיסייה Configuration.בSchema Explorer מוצגת תיעוד של סוגי ההגדרות הנתמכים, כדי לעזור לכם לכתוב את קובצי ה-YAML של ההגדרות. אחרי שאתם עורכים את קובצי ה-YAML של ההגדרות, אתם יכולים להריץ מחדש את העבודה כדי להשתמש בהגדרות החדשות.

כדי לגשת לכרטיסייה 'הגדרות':

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

   מעבר אל SQL Translation

2. ברשימת עבודות התרגום, מאתרים את העבודה שרוצים, לוחצים על שם העבודה או על אפשרויות נוספות > הצגת פרטים.

3. בחלון פרטי התרגום, לוחצים על הכרטיסייה הגדרה.

כדי להוסיף קובץ הגדרה חדש:

1. לוחצים על more_vert אפשרויות נוספות > יצירת קובץ YAML של הגדרות.
2. מופיעה חלונית שבה אפשר לבחור את הסוג, המיקום והשם של קובץ ה-YAML החדש של התצורה.
3. לוחצים על יצירה.

כדי לערוך קובץ תצורה קיים:

1. לוחצים על קובץ ה-YAML של ההגדרות.
2. עורכים את הקובץ ולוחצים על שמירה.
3. לוחצים על הרצה מחדש כדי להריץ משימת תרגום חדשה שמשתמשת בקובצי ה-YAML של ההגדרות הערוכות.

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

קובץ מיפוי של שמות פלט שנצרכו

קובץ ה-JSON הזה מכיל את כללי המיפוי של שמות הפלט שבהם נעשה שימוש במשימת התרגום. יכול להיות שהכללים בקובץ הזה יהיו שונים מהכללים של מיפוי שמות הפלט שציינתם למשימת התרגום, בגלל התנגשויות בכללי מיפוי השמות או בגלל היעדר כללי מיפוי שמות לאובייקטים של SQL שזוהו במהלך התרגום. צריך לבדוק את הקובץ הזה כדי לראות אם צריך לתקן את כללי מיפוי השמות. אם כן, צריך ליצור כללי מיפוי חדשים של שמות פלט שפותרים את הבעיות שזיהיתם, ולהריץ משימת תרגום חדשה.

קבצים מתורגמים

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

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

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

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

כדי להתחיל תרגום אינטראקטיבי של SQL באמצעות מזהה של הגדרת תרגום באצווה, פועלים לפי השלבים הבאים:

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

   מעבר אל SQL Translation

2. ברשימת משימות התרגום, מאתרים את המשימה שרוצים, ואז לוחצים על אפשרויות נוספות > פתיחת תרגום אינטראקטיבי.

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

כדי לנפות באגים בקובץ תרגום באצווה בכלי האינטראקטיבי לתרגום SQL, פועלים לפי השלבים הבאים:

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

   מעבר אל SQL Translation

2. ברשימת עבודות התרגום, מאתרים את העבודה שרוצים לראות, לוחצים על שם העבודה או על אפשרויות נוספות > הצגת פרטים.

3. בחלון פרטי התרגום, לוחצים על הכרטיסייה קוד.

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

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

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

6. כדי לשמור את קובץ הפלט הערוך בחזרה ב-Cloud Storage, לוחצים על שמירה > שמירה ב-GCS בכלי האינטראקטיבי לתרגום SQL.

מגבלות

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

לדוגמה, נניח שיש לכם UDF שנכתב ב-C ומחשב את הסכום של שני מספרים שלמים. כדי לוודא שהוראות SQL שמפנות אל UDF הזה יתורגמו בצורה נכונה, צריך ליצור UDF מסוג SQL שהוא placeholder ובעל אותה חתימה כמו ה-UDF מסוג C, כמו בדוגמה הבאה:

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

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

מכסות ומגבלות

• חלות מכסות של BigQuery Migration API.
• בכל פרויקט יכולות להיות עד 10 משימות תרגום פעילות.
• אין הגבלה על המספר הכולל של קבצי המקור והמטא-נתונים, אבל מומלץ להגביל את מספר הקבצים ל-1,000 כדי לשפר את הביצועים.

פתרון בעיות בתרגום

RelationNotFound או בעיות בתרגוםAttributeNotFound

אחרי תרגום של שאילתה באמצעות כלי התרגום של SQL באצווה, יכול להיות שתיתקלו בתרגום שנכשל עם השגיאה RelationNotFound או AttributeNotFound.

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

התרגום פועל בצורה הכי טובה עם DDL של מטא-נתונים. אם לא ניתן למצוא הגדרות של אובייקטים ב-SQL, מנוע התרגום מעלה בעיות מסוג RelationNotFound או AttributeNotFound. מומלץ להשתמש בכלי לחילוץ מטא-נתונים כדי ליצור חבילות של מטא-נתונים, כדי לוודא שכל הגדרות האובייקטים קיימות. הוספת מטא-נתונים היא הצעד הראשון המומלץ לפתרון רוב שגיאות התרגום, כי לעיתים קרובות היא יכולה לתקן שגיאות רבות אחרות שנגרמות באופן עקיף מחוסר במטא-נתונים.

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

תיקון בעיות בתרגום באמצעות Gemini

גרסת טרום-השקה

השימוש במוצר הזה או בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות. השימוש בתכונות ובמוצרים בגרסת טרום-GA הוא "כפי שהם" (As is), ויכול להיות שהתמיכה בהם תהיה מוגבלת. אתם יכולים לקרוא מידע נוסף בקטע תיאור שלבי ההשקה.

הערה: כדי לשלוח משוב או לבקש תמיכה בנוגע לתכונה הזו, אפשר לפנות אל [e-mail].

כדי לתקן עבודות תרגום שנכשלו עם השגיאות RelationNotFound או AttributeNotFound, אפשר גם להשתמש ב-Gemini כדי לנסות לפתור את הבעיות האלה באמצעות השלבים הבאים.

1. עוברים לדף פרטי התרגום ופותחים את הכרטיסייה הודעות ביומן.

2. לוחצים על השאילתה שבעמודה קטגוריה מופיעה לידה ההודעה RelationNotFound או AttributeNotFound.

3. לוחצים על הודעת השגיאה כדי לעבור לקובץ ולשורה שמכילים את השגיאה בכרטיסייה 'קוד'.

4. בעמודה פעולה, לוחצים על הצעה לתיקון.

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

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

תמחור

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

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

מידע נוסף על השלבים הבאים בהעברה של מחסן נתונים:

• סקירה כללית על מיגרציה
• הערכת תהליך ההעברה
• סקירה כללית של סכימה והעברת נתונים
• Data pipelines
• תרגום אינטראקטיבי של SQL
• אבטחת מידע ומשילות מידע
• הכלי לאימות נתונים