העברת קוד באמצעות המתרגם של SQL באצווה
הכלי לתרגום SQL באצווה ב-BigQuery מאפשר לתרגם סקריפטים שנכתבו בדיאלקטים אחרים של SQL לשאילתות GoogleSQL בכמות גדולה. אתם יכולים לשלוח ולבדוק את התוצאות של משימת תרגום באצווה דרך מסוףGoogle Cloud , דרך שורת הפקודה או באמצעות שרת ה-MCP של שירות ההעברה ל-BigQuery כדי להאיץ את ההעברה של עומסי עבודה גדולים.
כדי ליצור שילוב תוכנה בהתאמה אישית, צינור עיבוד נתונים אוטומטי של CI/CD או תהליך עבודה פרוגרמטי אחר, קוראים ישירות ל-BigQuery Migration API. למידע על ניבים נתמכים ומיקומי עיבוד, ראו ניבי SQL נתמכים ומיקומים.
לפני שמתחילים
לפני ששולחים משימת תרגום, צריך לבצע את השלבים הבאים.
הפעלת תרגומי SQL
מפעילים את ה-API הנדרש ומקבלים את ההרשאות שדרושות כדי להשתמש במתרגם SQL של BigQuery. מידע נוסף זמין במאמר הפעלת תרגומי SQL.
ההרשאות הנדרשות
כדי לקבל את ההרשאות שדרושות ליצירת משימות תרגום באמצעות המתרגם האינטראקטיבי, ה-API לתרגום או המתרגם של SQL באצווה, בקשו מהאדמין להקצות לכם את תפקידי ה-IAM הבאים במשאב parent:
-
צפייה במשימות ההעברה ומעקב אחריהן:
צפייה ב-MigrationWorkflow (
roles/bigquerymigration.viewer) -
שליחת משימות העברה:
עריכת MigrationWorkflow (
roles/bigquerymigration.editor) -
גישה לקטגוריות של Cloud Storage לקלט ולקבצים:
אדמין של אובייקטים ב-Storage (
roles/storage.objectAdmin) – בקטגוריית המקור והיעד של Cloud Storage.
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
התפקידים המוגדרים מראש האלו מכילים את ההרשאות שנדרשות כדי ליצור משימות תרגום באמצעות המתרגם האינטראקטיבי, ה-API לתרגום או המתרגם של SQL באצווה. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:
ההרשאות הנדרשות
כדי ליצור משימות תרגום באמצעות המתרגם האינטראקטיבי, ה-Translation API או המתרגם ב-SQL באצווה, נדרשות ההרשאות הבאות:
-
bigquerymigration.workflows.create -
bigquerymigration.workflows.get -
bigquerymigration.workflows.list -
bigquerymigration.workflows.delete -
bigquerymigration.subtasks.get -
bigquerymigration.subtasks.list -
storage.objects.get -
storage.objects.list -
storage.objects.create
יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.
כדי להגביל הגדרות ספציפיות של תהליך עבודה של תרגום בארגון, כמו איסור על הצעות של Gemini AI או הגבלת סוגי הפלט של התרגום, מגדירים מדיניות ארגונית בהתאמה אישית לשירות ההעברה ל-BigQuery.
איסוף קובצי מקור
קבצי המקור חייבים להיות קובצי טקסט שמכילים SQL תקין לניב המקור. קובצי המקור יכולים לכלול גם הערות. חשוב לוודא שה-SQL תקין, בכל דרך אפשרית.
יצירת קובצי מטא-נתונים
כדי לעזור לשירות ליצור תוצאות תרגום מדויקות יותר, מומלץ לספק קובצי מטא-נתונים. עם זאת, זו לא חובה.
כדי ליצור את פרטי המטא-נתונים, אתם יכולים להשתמש בכלי החילוץ dwh-migration-dumper בשורת הפקודה. אחרי שמכינים את קובצי המטא-נתונים, אפשר לכלול אותם יחד עם קובצי המקור בתיקיית המקור לתרגום. המתרגם מזהה אותם באופן אוטומטי ומשתמש בהם כדי לתרגם קובצי מקור, ואין צורך לקבוע הגדרות נוספות כדי להפעיל את האפשרות הזו.
כדי ליצור מידע על מטא-נתונים באמצעות הכלי dwh-migration-dumper, קראו את המאמר יצירת מטא-נתונים לתרגום.
יצירת קובצי YAML של הגדרות אישיות
אפשר גם ליצור קובצי YAML של הגדרות ולהשתמש בהם כדי להתאים אישית את תרגומי ה-Batch. אפשר להשתמש בקבצים האלה כדי לשנות את פלט התרגום בדרכים שונות. לדוגמה, אתם יכולים ליצור קובץ YAML של הגדרות אישיות כדי לשנות את האותיות הרישיות של אובייקט SQL במהלך התרגום.
כדי לכלול קובץ YAML של הגדרות במשימת התרגום, אפשר להשתמש באחת מהאפשרויות הבאות.
המסוף
מעלים את קובץ ה-YAML של ההגדרות לספרייה ב-Cloud Storage שמכילה את קובצי המקור. כשבוחרים את הספרייה הזו כמיקום קלט, משימת התרגום כוללת את קובץ התצורה מסוג YAML באופן אוטומטי.
gcloud
הדגלים שבהם משתמשים עם הפקודה gcloud alpha bq migration translate-batch תלויים במיקום שבו מאוחסן קובץ ה-YAML של ההגדרות:
- אם קובץ ה-YAML של ההגדרות נמצא באותה ספרייה כמו קובצי המקור, לא צריך דגלים נוספים. כשמגדירים את הספרייה הזו בדגל
--source-gcs-urisאו--source-local-dirs, המשימה כוללת את קובץ ה-YAML של ההגדרות באופן אוטומטי. - אם קובץ ה-YAML של ההגדרות האישיות מאוחסן בנפרד במחשב המקומי, משתמשים בדגל
--source-local-filesכדי להעלות אותו ולהוסיף אותו למשימה. - אם קובץ ה-YAML של ההגדרות מאוחסן בנפרד ב-Cloud Storage, צריך להשתמש בדגל
--source-gcs-filesכדי להוסיף אותו למשימה.
לדוגמה, הפקודה הבאה מעלה את קובצי המקור וקובץ YAML נפרד של הגדרות מהמכונה המקומית, ואז מריצה את משימת התרגום:
gcloud alpha bq migration translate-batch \ --source-dialect=SOURCE_DIALECT \ --target-dialect=TARGET_DIALECT \ --location=LOCATION \ --source-local-dirs=LOCAL_DIR=SOURCE_URI \ --source-local-files=LOCAL_CONFIG_YAML=CONFIG_YAML_URI \ --target-gcs-path=TARGET_URI
מחליפים את מה שכתוב בשדות הבאים:
-
LOCAL_CONFIG_YAML: הנתיב המקומי לקובץ ה-YAML של ההגדרות, למשל./configs/change-case.config.yaml. -
CONFIG_YAML_URI: ה-URI של Cloud Storage שאליו הפקודה מעלה את קובץ ה-YAML של ההגדרות האישיות, למשלgs://my_data_bucket/configs/change-case.config.yaml. ה-URI הזה חייב להיות מחוץ לספרייהSOURCE_URI.
לתיאורים של שאר ה-placeholders, ראו שליחת משימת תרגום.
MCP
מעלים את קובץ ה-YAML של ההגדרות לספרייה ב-Cloud Storage שמכילה את קובצי המקור. כשמתרגמים את הספרייה הזו באמצעות הכלי translate_batch_queries, משימת התרגום כוללת את קובץ ה-YAML של ההגדרות באופן אוטומטי. אם קובץ ה-YAML של ההגדרות מאוחסן במיקום נפרד ב-Cloud Storage מחוץ לספריית קובצי המקור, צריך לציין את ה-URI שלו ב-Cloud Storage בהנחיה. מידע נוסף מופיע במאמר שליחת משימת תרגום.
העלאת קובצי קלט ל-Cloud Storage
מעלים ל-Cloud Storage את קובצי המקור שמכילים את השאילתות והסקריפטים שרוצים לתרגם. אפשר גם להעלות קובצי מטא-נתונים או קובצי YAML של הגדרות אישיות לאותה קטגוריה של Cloud Storage ולספרייה שמכילה את קובצי המקור. מידע נוסף על יצירת קטגוריות והעלאת קבצים ל-Cloud Storage זמין במאמרים יצירת קטגוריות והעלאת אובייקטים ממערכת קבצים.
בוחרים איך לשלוח את משימת התרגום
יש שלוש אפשרויות לשליחת משימת תרגום באצווה:
מסוףGoogle Cloud : הגדרה ושליחה של משימה באמצעות ממשק משתמש. בגישה הזו צריך להעלות קובצי מקור ל-Cloud Storage.
Google Cloud CLI: שליחת משימה משורת הפקודה באמצעות ה-CLI של gcloud. הפקודה
translate-batchמקבלת את מיקומי המקור והיעד כדגלים, ויכולה להעלות ספריות וקבצים מקומיים ל-Cloud Storage. מידע נוסף מופיע במאמר שליחת משימת תרגום.שרת MCP של BigQuery Migration Service: שולחים משימה מאפליקציית AI או מסוכן שמחובר לשרת MCP של BigQuery Migration Service. בגישה הזו, קובצי המקור צריכים להיות ב-Cloud Storage. מידע נוסף מופיע במאמר שליחת משימת תרגום.
בכל האפשרויות, קובצי המקור צריכים להיות נגישים ב-Cloud Storage, וכולן יוצרות את אותו סוג של משימת תרגום. משימה ששולחים משורת הפקודה או מלקוח MCP עדיין מופיעה ברשימת משימות התרגום במסוף Google Cloud .
שליחת משימת תרגום
כדי להתחיל משימת תרגום ולראות את ההתקדמות שלה, אפשר להשתמש באחת מהאפשרויות הבאות. כדי לבדוק את התוצאות לאחר מכן, עיינו בקטע בדיקת פלט התרגום.
המסוף
השלבים האלה מבוססים על ההנחה שהעליתם קובצי מקור לקטגוריה של Cloud Storage.
כדי לשלוח בקשה לתרגום באצווה באמצעות מסוף Google Cloud , מבצעים את השלבים הבאים:
נכנסים לדף SQL Translation במסוף Google Cloud .
בחלונית SQL translation, לוחצים על Start translation.
בקטע Translation configuration, מזינים את הפרטים הבאים:
- בשדה השם המוצג, מזינים שם למשימת התרגום. השם יכול להכיל אותיות, מספרים או קווים תחתונים.
- בקטע Processing location, בוחרים את המיקום שבו רוצים להריץ את משימת התרגום. לדוגמה, אם אתם נמצאים באירופה ואתם לא רוצים שהנתונים שלכם יועברו מחוץ לאזור, בחרו באזור
eu. משימת התרגום פועלת בצורה הטובה ביותר כשבוחרים את אותו מיקום כמו הקטגוריה של קובץ המקור. - בקטע Source dialect, בוחרים את ניב ה-SQL שרוצים לתרגם.
- בשדה Target dialect, בוחרים באפשרות GoogleSQL.
לוחצים על הבא.
בקטע File location details, מציינים את הנתיבים ב-Cloud Storage שבהם רוצים להשתמש לקלט ולפלט של התרגום. אפשר להזין את הנתיבים בפורמט
bucket_name/folder_name/או להשתמש באפשרות עיון כדי לנווט לתיקייה.- בשדה Output directory location, מציינים את הנתיב לתיקיית היעד ב-Cloud Storage שבה יישמרו הקבצים המתורגמים. התיקייה הזו משמשת כתיקיית שורש לכל פלט התרגום.
- בוחרים מיקום אחד או יותר ב-Input directory locations שמכיל את הנתיב לקובצי ה-SQL שרוצים לתרגם.
- במקרה הצורך, אפשר לתת לכל ספריית קלט שם של ספריית משנה לפלט מתחת לספריית הפלט ברמה הבסיסית (root).
לוחצים על הבא.
בוחרים הגדרות אופציונליות שצריך כדי להתאים אישית את המטא-נתונים ופלט תרגום נוסף.
אופציונלי: כדי להתאים אישית את אופן התרגום, יוצרים קובצי YAML של הגדרות וממקמים אותם בקטגוריית הקלט של Cloud Storage. אפשר להשתמש בקבצים האלה כדי לשנות שמות של אובייקטים, להפעיל אופטימיזציות, לשפר תרגומים באמצעות Gemini ועוד. למידע נוסף על קובצי YAML של הגדרות, ראו יצירת קובץ YAML של הגדרות.
כדי להתחיל את משימת התרגום, לוחצים על Create.
אחרי שיוצרים את משימת התרגום, אפשר לראות את הסטטוס שלה ברשימת משימות התרגום.
gcloud
כדי לשלוח משימת תרגום באצווה, משתמשים בפקודה gcloud alpha bq migration translate-batch.
הדגלים שבהם משתמשים כדי לזהות את קובצי המקור תלויים במיקום של הקבצים – ב-Cloud Storage או במחשב המקומי.
תרגום קובצי SQL ב-Cloud Storage
כדי לתרגם קובצי SQL שכבר העליתם ל-Cloud Storage, צריך לזהות את ספריות המקור באמצעות הדגל --source-gcs-uris. אם רוצים לכלול קבצים שלא נמצאים ב---source-gcs-uris, אפשר להשתמש בדגל --source-gcs-files:
gcloud alpha bq migration translate-batch \
--source-dialect=SOURCE_DIALECT \
--target-dialect=TARGET_DIALECT \
--location=LOCATION \
--source-gcs-uris=SOURCE_URI \
--target-gcs-path=TARGET_URI
מחליפים את מה שכתוב בשדות הבאים:
-
SOURCE_DIALECT: הניב של קובצי ה-SQL של המקור, כמוteradata. במאמר ניבי SQL נתמכים תוכלו למצוא רשימה של הערכים הנתמכים. -
TARGET_DIALECT: הניב שאליו רוצים לתרגם את קובצי המקור. לדוגמה,bigquery. -
LOCATION: המיקום שבו המשימה מעובדת, למשלus. -
SOURCE_URI: הספרייה ב-Cloud Storage שמכילה את קובצי המקור, למשלgs://my_data_bucket/input/. -
TARGET_URI: הספרייה ב-Cloud Storage שאליה נשלחים הקבצים המתורגמים, למשלgs://my_data_bucket/output/.
תרגום קובצי SQL במחשב המקומי
כדי לתרגם קבצים שנמצאים במכונה המקומית, ממפים כל ספרייה מקומית ל-URI של Cloud Storage באמצעות הדגל --source-local-dirs. הפקודה מעלה את הספרייה ל-URI הזה, ואז כוללת את ה-URI במשימת התרגום, כך שאתם לא צריכים להעלות את הקבצים בעצמכם:
gcloud alpha bq migration translate-batch \
--source-dialect=SOURCE_DIALECT \
--target-dialect=TARGET_DIALECT \
--location=LOCATION \
--source-local-dirs=LOCAL_DIR=SOURCE_URI \
--target-gcs-path=TARGET_URI
מחליפים את LOCAL_DIR בספרייה המקומית שמכילה את קובצי המקור, למשל ./input_queries. במאמר תרגום קובצי SQL ב-Cloud Storage מופיעים תיאורים של שאר ה-placeholders.
כדי למפות קבצים ספציפיים במקום ספריות, משתמשים בדגל --source-local-files.
הוספת דגלים אופציונליים
כדי ליצור הצעות של Gemini לצד ה-SQL המתורגם, מוסיפים את הדגל --enable-ai-suggestion.
כברירת מחדל, הפקודה ממתינה עד לסיום משימת התרגום. כדי לשלוח את המשימה ולחזור מיד, מוסיפים את הדגל --async. הפקודה מדפיסה מזהה תרגום שאפשר להעביר לפקודה gcloud alpha bq migration translation describe כדי לבדוק את סטטוס המשימה:
gcloud alpha bq migration translation describe TRANSLATION_ID \
--location=LOCATION
אחזור קובצי הפלט
משימת התרגום כותבת את התוצאות שלה לספריית Cloud Storage שהגדרתם בדגל --target-gcs-path. בספריית היעד הזו נמצאים הקבצים המתורגמים, דוח סיכום התרגום וכל קובצי ההצעות של ה-AI.
כדי להעתיק את הפלט למחשב המקומי, משתמשים בפקודה הבאה:
gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY
מחליפים את מה שכתוב בשדות הבאים:
-
TARGET_URI: ה-URI הבסיסי של היעד, למשלgs://my_data_bucket/output/. -
LOCAL_DIRECTORY: הספרייה המקומית שאליה מועברים הקבצים.
המשימה מופיעה גם ברשימת משימות התרגום במסוףGoogle Cloud , למרות ששלחתם אותה משורת הפקודה. כדי לבדוק את איכות התרגום, עיינו בקטע בדיקת פלט התרגום.
MCP
כדי לשלוח משימת תרגום באצווה מאפליקציה או מסוכן AI, מחברים את לקוח ה-MCP לשרת ה-MCP של שירות ההעברה ל-BigQuery. הוראות להגדרה והתפקידים הנדרשים מפורטים במאמר הגדרת לקוח MCP לשימוש בשרת MCP של BigQuery Migration Service.
מעלים את קובצי ה-SQL של הקלט וכל קובץ ZIP של מטא-נתונים או קובץ YAML של הגדרות אישיות ל-Cloud Storage, ואז מנחים את לקוח ה-MCP לתרגם את הקבצים:
Translate the DIALECT SQL files in SOURCE_URI into GoogleSQL and write the output to TARGET_URI. Use PROJECT_NUMBER and LOCATION.
מחליפים את מה שכתוב בשדות הבאים:
-
DIALECT: הניב של קובצי ה-SQL שאתם מתרגמים, כמוTeradata. במאמר ניבי SQL נתמכים תוכלו למצוא רשימה של הערכים הנתמכים. -
SOURCE_URI: הספרייה ב-Cloud Storage שמכילה את קובצי הקלט, למשלgs://my_data_bucket/input/. -
TARGET_URI: ספרייה ריקה ב-Cloud Storage שמקבלת את הפלט, כמוgs://my_data_bucket/output/. -
PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud. -
LOCATION: המיקום שבו המשימה מעובדת, למשלus.
כשמשתמשים בהנחיה הזו, לקוח ה-MCP מפעיל את הכלי translate_batch_queries, ואז מפעיל מדי פעם את הכלי fetch_batch_translation עד שמצב התרגום הוא SUCCEEDED או FAILED. השרת כותב את קובצי ה-SQL המתורגמים ואת דוח הסיכום של translation_report.csv ב-TARGET_URI. המשימה מופיעה גם ברשימת משימות התרגום במסוף Google Cloud . דוגמאות נוספות להנחיות
תרגום מטא-נתונים
בנוסף לתרגום סקריפטים של SQL, אתם יכולים לתרגם את המטא-נתונים שמתארים את מחסן הנתונים של המקור. משימת תרגום של מטא-נתונים קוראת את קובצי המטא-נתונים שחילצתם ממערכת המקור, וכותבת הצהרות של שפת הגדרת נתונים (DDL) ב-GoogleSQL שיוצרות מחדש את האובייקטים האלה ב-BigQuery.
הקלט הוא קובץ ZIP אחד או יותר של מטא-נתונים. כדי ללמוד איך ליצור את הקבצים האלה באמצעות הכלי dwh-migration-dumper, קראו את המאמר יצירת מטא-נתונים לתרגום.
אפשר לתרגם מטא-נתונים באמצעות מסוף Google Cloud , ה-CLI של gcloud או שרת ה-MCP של שירות ההעברה ל-BigQuery. בוחרים באחת מהאפשרויות הבאות:
המסוף
תרגום מטא-נתונים הוא אפשרות פלט במשימת תרגום רגילה:
- כדי להגדיר משימה, פועלים לפי השלבים שמפורטים בקטע שליחת משימת תרגום, ומשתמשים בספריית Cloud Storage שמכילה את קובצי ה-ZIP של המטא-נתונים כמיקום קלט.
- בקטע Optional settings, בוחרים באפשרות DDL.
- לוחצים על Create כדי ליצור את המשימה.
המשימה כותבת את הצהרות ה-DDL המתורגמות לספריית הפלט, לצד כל SQL מתורגם.
gcloud
אפשר לתרגם מטא-נתונים כמשימה נפרדת, או כפלט נוסף של משימת תרגום SQL באצווה.
תרגום של המטא-נתונים בלבד
אם הקלט הוא קובצי ZIP של מטא-נתונים ואין לכם SQL לתרגום, השתמשו בפקודה gcloud alpha bq migration translate-metadata:
gcloud alpha bq migration translate-metadata \ --source-dialect=SOURCE_DIALECT \ --target-dialect=TARGET_DIALECT \ --location=LOCATION \ --source-gcs-uris=SOURCE_URI \ --target-gcs-path=TARGET_URI
מחליפים את מה שכתוב בשדות הבאים:
-
SOURCE_DIALECT: הניב של המטא-נתונים של המקור, כמוteradata. במאמר ניבי SQL נתמכים תוכלו למצוא רשימה של הערכים הנתמכים. -
TARGET_DIALECT: הניב של טבלאות היעד. לדוגמה,bigquery. -
LOCATION: המיקום שבו המשימה מעובדת, למשלus. -
SOURCE_URI: הספרייה ב-Cloud Storage שמכילה את קובצי ה-ZIP של המטא-נתונים, למשלgs://my_data_bucket/metadata/. -
TARGET_URI: הספרייה ב-Cloud Storage שמקבלת את הצהרות ה-DDL המתורגמות, למשלgs://my_data_bucket/ddl_output/.
כדי להצביע על קובצי ZIP ספציפיים של מטא-נתונים במקום על ספרייה, משתמשים בדגל --source-gcs-files. כדי להעלות קובצי מטא-נתונים מהמכונה המקומית כחלק מהמשימה, משתמשים בדגל --source-local-dirs או --source-local-files.
כמו במשימת תרגום באצווה, הפקודה ממתינה לסיום המשימה. מוסיפים את הדגל --async כדי לשלוח את המשימה ולהחזיר מזהה תרגום באופן מיידי.
תרגום מטא-נתונים כחלק מתרגום SQL באצווה
אם הקלט של תרגום האצווה כבר כולל את קובצי ה-ZIP של המטא-נתונים, אין צורך במשימה שנייה. מוסיפים את metadata לפלטים של התרגום של המשימה באצווה עם הדגל --target-types, והמשימה כותבת את ה-SQL המתורגם ואת הצהרות ה-DDL בהרצה אחת:
gcloud alpha bq migration translate-batch \ --source-dialect=SOURCE_DIALECT \ --target-dialect=TARGET_DIALECT \ --location=LOCATION \ --source-gcs-uris=SOURCE_URI \ --target-gcs-path=TARGET_URI \ --target-types=sql,metadata
למידע על דגלים אחרים שאפשר להשתמש בהם עם הפקודה translate-batch, קראו את המאמר שליחת משימת תרגום.
MCP
כדי לתרגם קובץ ZIP של מטא-נתונים ב-Cloud Storage מלקוח MCP שמחובר לשרת ה-MCP של BigQuery Migration Service, מזינים את ההנחיה הבאה ללקוח ה-MCP:
Translate the DIALECT metadata file METADATA_FILE_URI into BigQuery DDL. Write the output to TARGET_URI. Use PROJECT_NUMBER and LOCATION.
מחליפים את METADATA_FILE_URI בנתיב של קובץ ה-ZIP של המטא-נתונים ב-Cloud Storage, למשל gs://my_data_bucket/metadata.zip. לתיאורים של שאר הפלייסהולדרים, ראו שליחת משימת תרגום.
כשמשתמשים בהנחיה הזו, לקוח ה-MCP מפעיל את הכלי translate_metadata, ואז מפעיל מדי פעם את הכלי fetch_batch_translation עד שהמצב הוא SUCCEEDED או FAILED. השרת כותב את הצהרות ה-DDL שנוצרו ואת מיפויי הטבלאות ב-TARGET_URI.
יצירת DDL של מקור
כשה-SQL של המקור מפנה לטבלאות שאין לכם את ההגדרות שלהן, המתרגם לא תמיד יכול לפתור את האובייקטים, מה שמוביל לבעיות מסוג RelationNotFound או AttributeNotFound.
הדרך הטובה ביותר לפתור את הבעיות האלה היא לספק את ההגדרות האמיתיות של אובייקטי המקור. מריצים את הכלי dwh-migration-dumper במערכת המקור וכוללים את קובץ ה-ZIP של המטא-נתונים שנוצר בקלט של התרגום. הוראות מפורטות זמינות במאמר יצירת מטא-נתונים לתרגום.
המטא-נתונים שחולצו מתארים את האובייקטים שלכם בצורה מדויקת, כך שהמתרגם פותר אותם בלי ניחושים.
אם אתם לא יכולים לחלץ מטא-נתונים, למשל כשאין לכם יותר גישה למערכת המקור, אתם יכולים לבקש מ-Gemini להסיק את הצהרות ה-DDL החסרות מה-SQL של המקור. Gemini מסיק את הצהרות ה-DDL האלה מהאופן שבו האובייקטים משמשים בשאילתות שלכם, לכן תמיד צריך לבדוק ולאמת את ההצהרות האלה לפני שמשתמשים בהן.
אתם יכולים ליצור DDL של מקור לתרגומים באמצעותGoogle Cloud מסוף, ה-CLI של gcloud או שרת ה-MCP של שירות ההעברה ל-BigQuery. בוחרים באחת מהאפשרויות הבאות:
המסוף
Gemini יוצר הצעות ל-DDL של המקור כחלק ממשימת תרגום רגילה:
- כדי להגדיר משימה, פועלים לפי השלבים שמפורטים בקטע שליחת משימת תרגום.
- בהגדרות אופציונליות, בוחרים באפשרות הצעות מ-Gemini AI.
- לוחצים על Create כדי ליצור את המשימה.
אם התרגום יוצר בעיות מסוג RelationNotFound או AttributeNotFound, המשימה יוצרת הצעות להצהרות DDL במקור לאובייקטים שלא נפתרו. המשימה גם מתרגמת את ה-SQL, כך שאין צורך במשימה נפרדת.
gcloud
הפקודה gcloud alpha bq migration translation generate-source-ddl קוראת את ה-SQL של המקור ומחזירה הצעות להצהרות DDL של המקור:
gcloud alpha bq migration translation generate-source-ddl \ --source-dialect=SOURCE_DIALECT \ --target-dialect=TARGET_DIALECT \ --location=LOCATION \ --source-gcs-uris=SOURCE_URI \ --target-gcs-path=TARGET_URI
מחליפים את SOURCE_URI בספרייה ב-Cloud Storage שמכילה את קובצי המקור ב-SQL, ואת TARGET_URI בספרייה ב-Cloud Storage שמקבלת את הצהרות ה-DDL שנוצרו. שאר הפלייסהולדרים זהים לאלה שמתוארים בקטע תרגום מטא-נתונים.
כדי ליצור הצעות כחלק ממשימת תרגום, מוסיפים את הדגל --enable-ai-suggestion לפקודה translate-batch.
MCP
כדי ליצור הצעות ל-DDL של המקור לקובצי ה-SQL ב-Cloud Storage מלקוח MCP שמחובר לשרת ה-MCP של שירות ההעברה ל-BigQuery, מזינים את ההנחיה הבאה ללקוח ה-MCP:
Generate DDL for the DIALECT SQL files in SOURCE_URI and write the output to TARGET_URI. Use PROJECT_NUMBER and LOCATION.
לתיאור של ה-placeholders, קראו את המאמר שליחת משימת תרגום.
כשמשתמשים בהנחיה הזו, לקוח ה-MCP מפעיל את הכלי generate_batch_ddl_suggestion, ואז מפעיל מדי פעם את הכלי fetch_batch_ddl_suggestion עד שהמצב הוא SUCCEEDED או FAILED. השרת כותב את הצעות הצהרות ה-DDL לספריית Cloud Storage שמוחזרת בתגובה של fetch_batch_ddl_suggestion. כדי לתרגם מחדש באמצעות הצהרות ה-DDL המוצעות, מעתיקים אותן כקובצי SQL לא מכווצים לספרייה ב-SOURCE_URI ומריצים שוב את translate_batch_queries.
אחר כך תוכלו לספק את הצהרות ה-DDL שנוצרו כקלט למשימת תרגום מאוחרת יותר, כדי לשפר את איכות התרגום. מידע נוסף זמין במאמר בעיות בתרגום של RelationNotFound או AttributeNotFound.
בדיקת הפלט של התרגום
כשמריצים משימת תרגום באצווה, המתרגם באצווה של SQL כותב את הקבצים המתורגמים, את דוח הסיכום ואת קובצי ההצעות של Gemini בנתיב היעד שציינתם ב-Cloud Storage. במסוףGoogle Cloud יש גם ממשק שבו אפשר לראות את קובצי הפלט, לבדוק בעיות בתרגום ולנהל את קובצי התצורה, גם אם שלחתם את המשימה ממסוף Google Cloud , משורת הפקודה או מלקוח MCP.
קובצי פלט של תרגום
משימת התרגום כותבת קובצי פלט לנתיב היעד ב-Cloud Storage, בספריות הבאות:
-
sql/: קובצי ה-SQL המתורגמים שמנוע התרגום יוצר אחרי החלת הכללים בקובצי*.config.yaml. אם חליםSOURCE_SQLכללים בקובצי*.ai_config.yaml, המנוע מתרגם את קובצי ה-SQL שנכתבו מחדש מ-source_sql_query_customization_suggestion/במקום את קובצי הקלט המקוריים של SQL. -
metadata/: קובצי SQL שמכילים את הצהרות ה-DDL המתורגמות לטבלאות ולתצוגות בקובצי ה-ZIP של המטא-נתונים שהזנתם, כשאתם מפעילים את תרגום המטא-נתונים. הספרייה הזו כוללת גם ספריית משנה בשםconfig/, שמכילה את המטא-נתונים המתורגמים של הטבלה בפורמט YAML. -
report/: קובצי דוחות ברמת המשימה. הספרייה הזו כוללת את דוח הסיכום שלtranslation_report.csv. -
source_sql_query_customization_suggestion/: קובצי מקור משוכתבים של SQL ש-Gemini יוצר לפני התרגום, על ידי החלת כלליSOURCE_SQLבקובצי*.ai_config.yamlעל קובצי הקלט המקוריים של SQL. target_sql_query_customization_suggestion/: קובצי SQL משוכתבים של יעד ש-Gemini יוצר על ידי החלת כלליTARGET_SQLבקובצי*.ai_config.yamlעל קובצי SQL המתורגמים ב-sql/.translation_explanation_suggestion/: קובצי טקסט שמכילים הסברים שנוצרו על ידי Gemini לקובצי ה-SQL המתורגמים ב-sql/.-
source_sql_metadata_generation_suggestion/: קובץgenerated_metadata.sqlשמכיל הצעות של Gemini להצהרות DDL במקור לאובייקטים במקור שלא נפתרו בקובצי ה-SQL שהוזנו.
ה-job כותב את הספריות *_suggestion/ רק כשמפעילים את ההצעות של Gemini AI. בספריות sql/, source_sql_query_customization_suggestion/, target_sql_query_customization_suggestion/ ו-translation_explanation_suggestion/, כל קובץ פלט שומר על הנתיב היחסי של קובץ ה-SQL המקורי שלו מספריית הקלט. הקבצים בספרייה translation_explanation_suggestion/ הם קובצי טקסט שנקראים על שם קובצי ה-SQL המקוריים שלהם, עם סיומת שם קובץ אחרת. לדוגמה, ההסבר ל-queries/report.sql הוא translation_explanation_suggestion/queries/report.txt.
פלט במסוףGoogle Cloud
אתם יכולים להשתמש במסוף Google Cloud כדי להציג את קובצי הפלט ב-Cloud Storage ולבדוק את תוצאות התרגום. כדי לראות את פרטי משימת התרגום:
נכנסים לדף SQL Translation במסוף Google Cloud .
ברשימת משימות התרגום, מאתרים את המשימה שרוצים לראות את פרטי התרגום שלה. לאחר מכן לוחצים על שם משימת התרגום. אתם יכולים לראות תרשים סנקי שממחיש את האיכות הכוללת של המשימה, את מספר שורות הקוד של הקלט (לא כולל שורות ריקות והערות) ורשימה של בעיות שהתרחשו במהלך תהליך התרגום. כדאי לתקן את הבעיות לפי הסדר, משמאל לימין. בעיות בשלב מוקדם יכולות לגרום לבעיות נוספות בשלבים הבאים.
מעבירים את העכבר מעל פסי השגיאות או האזהרות, וקוראים את ההצעות כדי להחליט מה לעשות כדי לנפות באגים במשימת התרגום.
בכרטיסייה Log Summary אפשר לראות סיכום של בעיות התרגום, כולל קטגוריות של בעיות, פעולות מומלצות ותדירות ההתרחשות של כל בעיה. אפשר ללחוץ על העמודות בתרשים סנקי כדי לסנן את הבעיות. אפשר גם לבחור קטגוריית בעיה כדי לראות הודעות ביומן שמשויכות לקטגוריה הזו.
בכרטיסייה Log Messages אפשר לראות פרטים נוספים על כל בעיה בתרגום, כולל קטגוריית הבעיה, ההודעה הספציפית על הבעיה וקישור לקובץ שבו הבעיה התרחשה. אפשר ללחוץ על העמודות בתרשים סנקי כדי לסנן את הבעיות. אתם יכולים לבחור בעיה בכרטיסייה Log Message כדי לפתוח את הכרטיסייה Code, שבה מוצגים קובץ הקלט וקובץ הפלט, אם רלוונטי.
לוחצים על הכרטיסייה Job details כדי לראות את פרטי ההגדרות של משימת התרגום.
דוח סיכום
דוח הסיכום הוא קובץ CSV שמכיל טבלה של כל הודעות האזהרה והשגיאה שהתקבלו במהלך משימת התרגום.
כדי לראות את קובץ הסיכום במסוף Google Cloud :
נכנסים לדף SQL Translation במסוף Google Cloud .
ברשימת משימות התרגום, מאתרים את המשימה הרצויה ולוחצים על שם המשימה או על אפשרויות נוספות > הצגת פרטים.
בכרטיסייה Job details, בקטע Translation report, לוחצים על translation_report.csv.
בדף Object details, לוחצים על הערך בשורה כתובת URL לאימות כדי לראות את הקובץ בדפדפן.
בטבלה הבאה מתוארות העמודות בקובץ הסיכום:
| עמודה | תיאור |
|---|---|
| חותמת הזמן | חותמת הזמן של מועד הבעיה. |
| FilePath | הנתיב לקובץ המקור שהבעיה משויכת אליו. |
| FileName | שם קובץ המקור שבו נמצאה הבעיה. |
| ScriptLine | מספר השורה שבה התרחשה הבעיה. |
| ScriptColumn | מספר העמודה שבה התרחשה הבעיה. |
| TranspilerComponent | הרכיב הפנימי של מנוע התרגום שבו התרחשה האזהרה או השגיאה. יכול להיות שהעמודה הזו ריקה. |
| סביבה | סביבת הניב של התרגום שמשויכת לאזהרה או לשגיאה. יכול להיות שהעמודה הזו ריקה. |
| ObjectName | אובייקט ה-SQL בקובץ המקור שמשויך לאזהרה או לשגיאה. יכול להיות שהעמודה הזו ריקה. |
| חוּמרה | חומרת הבעיה: אזהרה או שגיאה. |
| קטגוריה | קטגוריית הבעיה בתרגום. |
| SourceType | המקור של הבעיה הזו. הערך בעמודה הזו יכול להיות SQL, שמציין בעיה בקובצי ה-SQL של הקלט, או METADATA, שמציין בעיה בחבילת המטא-נתונים. |
| הודעה | הודעת האזהרה או השגיאה לגבי הבעיה בתרגום. |
| ScriptContext | קטע הקוד של SQL בקובץ המקור שמשויך לבעיה. |
| פעולה | הפעולה שאנחנו ממליצים לבצע כדי לפתור את הבעיה. |
הכרטיסייה "קוד"
בכרטיסיית הקוד אפשר לראות מידע נוסף על קובצי הקלט והפלט של משימת תרגום מסוימת. בכרטיסייה Code, אתם יכולים לבדוק את הקבצים ששימשו במשימת התרגום, לבחון השוואה בטבלה של קובץ קלט והתרגום שלו כדי לאתר אי-דיוקים, ולראות סיכומי יומנים והודעות של קובץ ספציפי במשימה.
כדי לגשת לכרטיסיית הקוד, פועלים לפי השלבים הבאים:
נכנסים לדף SQL Translation במסוף Google Cloud .
ברשימת משימות התרגום, מאתרים את המשימה הרצויה ולוחצים על שם המשימה או על אפשרויות נוספות > הצגת פרטים.
לוחצים על כרטיסיית הקוד. הכרטיסייה "קוד" כוללת את החלוניות הבאות:
- סייר הקבצים: מכיל את כל קובצי ה-SQL שמשמשים לתרגום. לוחצים על קובץ כדי לראות את הקלט והפלט של התרגום שלו, ובעיות שקשורות לתרגום.
- קלט משופר באמצעות Gemini: קלט ה-SQL שתורגם על ידי מנוע התרגום. אם ציינתם כללי התאמה אישית של Gemini ל-SQL המקורי בהגדרות של Gemini, המתרגם משנה קודם את הקלט המקורי ואז מתרגם את הקלט המשופר של Gemini. כדי לראות את הקלט המקורי, לוחצים על View original input.
- פלט התרגום: תוצאת התרגום. אם ציינתם כללי התאמה אישית של Gemini ל-SQL היעד בהגדרות של Gemini, הטרנספורמציה תתבצע על התוצאה המתורגמת כפלט משופר של Gemini. אם יש פלט משופר של Gemini, אתם יכולים ללחוץ על הכפתור Gemini suggestion כדי לבדוק אותו.
אופציונלי: כדי להציג קובץ קלט ואת קובץ הפלט שלו במתרגם SQL האינטראקטיבי של BigQuery, לוחצים על Edit. אתם יכולים לערוך את הקבצים ולשמור את קובץ הפלט בחזרה ב-Cloud Storage.
הכרטיסייה "הגדרה"
בכרטיסייה Configuration אפשר להוסיף, לשנות את השם, להציג או לערוך את קובצי ה-YAML של ההגדרות האישיות. ב-Schema Explorer מוצג התיעוד של סוגי ההגדרות הנתמכים, כדי לעזור לכם לכתוב את קובצי ה-YAML של ההגדרות. אחרי שאתם עורכים את קובצי ה-YAML של ההגדרות, אתם יכולים להריץ מחדש את המשימה כדי להשתמש בהגדרות החדשות.
כדי לגשת לכרטיסיית ההגדרות:
נכנסים לדף SQL Translation במסוף Google Cloud .
ברשימת משימות התרגום, מאתרים את המשימה הרצויה ולוחצים על שם המשימה או על אפשרויות נוספות > הצגת פרטים.
בחלון Translation details, לוחצים על הכרטיסייה Configuration.
כדי להוסיף קובץ תצורה חדש:
- לוחצים על more_vert אפשרויות נוספות > יצירת קובץ YAML של הגדרות אישיות.
- מופיע חלונית שבה אפשר לבחור את הסוג, המיקום והשם של קובץ ה-YAML החדש של ההגדרות האישיות.
- לוחצים על יצירה.
כדי לערוך קובץ תצורה קיים:
- לוחצים על קובץ ה-YAML של ההגדרות.
- עורכים את הקובץ ולוחצים על שמירה.
- לוחצים על Re-run כדי להריץ משימת תרגום חדשה שמשתמשת בקובצי ה-YAML של ההגדרות שנערכו.
כדי לשנות את השם של קובץ תצורה קיים, לוחצים על more_vert More options > Rename.
טיפול בפונקציות SQL שלא נתמכות באמצעות פונקציות עזר מוגדרות על ידי המשתמש (UDF)
כשמתרגמים SQL מדיאלקט מקור ל-BigQuery, יכול להיות שלפונקציות מסוימות לא יהיה מקבילה ישירה. כדי לפתור את הבעיה, שירות ההעברה ל-BigQuery (והקהילה הרחבה יותר של BigQuery) מספקים פונקציות עזר בהגדרת המשתמש (UDF) שמשכפלות את ההתנהגות של הפונקציות האלה בניב המקור שלא נתמך.
הפונקציות האלה מוגדרות על ידי המשתמשים, ולרוב נמצאות במערך הנתונים הציבורי bqutil. כך אפשר להפנות אליהן בהתחלה שאילתות מתורגמות בפורמט bqutil.<dataset>.<function>(). לדוגמה, bqutil.fn.cw_count().
שיקולים לגבי סביבות ייצור
אמנם bqutil מציע גישה נוחה לפונקציות העזר האלה של UDF לצורך תרגום ובדיקה ראשוניים, אבל לא מומלץ להסתמך ישירות על bqutil לעומסי עבודה בסביבת הייצור מהסיבות הבאות:
- ניהול גרסאות: הפרויקט
bqutilמארח את הגרסה האחרונה של הפונקציות האלה, ולכן ההגדרות שלהן יכולות להשתנות עם הזמן. הסתמכות ישירה עלbqutilעלולה להוביל להתנהגות בלתי צפויה או לשינויי תוכנה שעלולים לגרום לכשל בשאילתות בסביבת הייצור, אם הלוגיקה של ה-UDF תעודכן. - בידוד של יחסי תלות: פריסת פונקציות UDF בפרויקט שלכם מבודדת את סביבת הייצור משינויים חיצוניים.
- התאמה אישית: יכול להיות שתצטרכו לשנות או לבצע אופטימיזציה של הפונקציות האלה כדי להתאים אותן ללוגיקה העסקית או לדרישות הביצועים הספציפיות שלכם. אפשר לעשות את זה רק אם הם נמצאים בפרויקט שלכם.
- אבטחה ופיקוח: יכול להיות שמדיניות האבטחה של הארגון שלכם מגבילה את הגישה הישירה למערכי נתונים ציבוריים כמו
bqutilלצורך עיבוד נתוני ייצור. העתקת פונקציות UDF לסביבה המבוקרת שלכם תואמת למדיניות כזו.
פריסת פונקציות עזר בהתאמה אישית בפרויקט
כדי לתת לכם שליטה מלאה על הגרסה, ההתאמה האישית והגישה של פונקציות ה-UDF, אנחנו ממליצים לפרוס פונקציות UDF מסייעות בפרויקט ובמערך הנתונים שלכם, לשימוש אמין ויציב בסביבת הייצור. במאמר פריסת פונקציות ה-UDF מוסבר איך לפרוס פונקציות UDF בסביבה שלכם, כולל הסקריפטים הנדרשים.
פתרון בעיות
בקטע הזה מוסבר איך לנפות באגים בשאילתות ספציפיות ואיך לפתור את שגיאות התרגום הנפוצות ביותר.
ניפוי באגים של שאילתות SQL שתורגמו באצווה באמצעות המתרגם האינטראקטיבי של SQL
אתם יכולים להשתמש במתרגם האינטראקטיבי של SQL ב-BigQuery כדי לבדוק שאילתת SQL או לנפות בה באגים, באמצעות אותם מטא-נתונים או מידע על מיפוי אובייקטים כמו במסד הנתונים של המקור. אחרי שמסיימים משימת תרגום באצווה, BigQuery יוצר מזהה הגדרת תרגום שמכיל מידע על המטא-נתונים של המשימה, מיפוי האובייקטים או נתיב החיפוש של הסכימה, בהתאם לשאילתה. אתם משתמשים במזהה ההגדרה של תרגום באצווה עם המתרגם האינטראקטיבי של SQL כדי להריץ שאילתות SQL עם ההגדרה שצוינה.
אפשר לנפות באגים בשאילתות SQL שתורגמו באצווה באמצעות מסוףGoogle Cloud או ה-CLI של gcloud. בוחרים באחת מהאפשרויות הבאות:
המסוף
כדי להתחיל תרגום אינטראקטיבי של SQL באמצעות מזהה הגדרה של תרגום באצווה:
נכנסים לדף SQL Translation במסוף Google Cloud .
ברשימת משימות התרגום, מאתרים את המשימה הרצויה ולוחצים על אפשרויות נוספות > פתיחת תרגום אינטראקטיבי.
המתרגם האינטראקטיבי של SQL ב-BigQuery נפתח עם מזהה ההגדרה המתאים לתרגום באצווה. כדי לראות את מזהה הגדרות התרגום של התרגום האינטראקטיבי, לוחצים על Tools > Query translation > Translation settings בכלי האינטראקטיבי לתרגום SQL.
כדי לנפות באגים בקובץ תרגום באצווה במתרגם האינטראקטיבי של SQL, פועלים לפי השלבים הבאים:
נכנסים לדף SQL Translation במסוף Google Cloud .
ברשימת משימות התרגום, מאתרים את המשימה הרלוונטית ולוחצים על שם המשימה או על אפשרויות נוספות > הצגת פרטים.
בחלון Translation details, לוחצים על הכרטיסייה Code.
בסייר הקבצים, לוחצים על שם הקובץ כדי לפתוח אותו.
ליד שם קובץ הפלט, לוחצים על Edit כדי לפתוח את הקבצים במתרגם האינטראקטיבי של SQL (גרסת טרום-השקה (Preview)).
קובצי הקלט והפלט מאוכלסים במתרגם האינטראקטיבי של SQL, שמשתמש עכשיו במזהה ההגדרה המתאים של תרגום באצווה.
כדי לשמור את קובץ הפלט הערוך בחזרה ב-Cloud Storage, לוחצים על Save > Save To GCS במתרגם ה-SQL האינטראקטיבי.
gcloud
כדי לתרגם מחדש ולבדוק שאילתה אחת בלי לפתוח את מסוףGoogle Cloud , משתמשים בפקודה gcloud alpha bq migration translate.
האפשרות הזו שימושית כשמצמצמים בעיה בתרגום באצווה לשאילתה אחת ורוצים לחזור עליה באופן מקומי.
gcloud alpha bq migration translate \ --source-dialect=SOURCE_DIALECT \ --target-dialect=TARGET_DIALECT \ --location=LOCATION \ --input-file=INPUT_FILE \ --output-file=OUTPUT_FILE \ --translation-log-file=LOG_FILE \ --explanation-output-file=EXPLANATION_FILE
מחליפים את מה שכתוב בשדות הבאים:
-
INPUT_FILE: הקובץ המקומי שמכיל את השאילתה שרוצים לתרגם. אם משמיטים את הדגל הזה, הפקודה קוראת את השאילתה מקלט סטנדרטי (stdin). -
OUTPUT_FILE: הקובץ המקומי שמקבל את השאילתה המתורגמת. אם לא כוללים את הדגל הזה, הפקודה כותבת את השאילתה לפלט סטנדרטי (stdout). -
LOG_FILE: קובץ ה-YAML המקומי שמקבל את יומני התרגום, שמכילים את אותן הודעות על בעיות שמופיעות במסוףGoogle Cloud בכרטיסייה Log Messages. -
EXPLANATION_FILE: הקובץ המקומי שמקבל הסבר על התרגום שנוצר על ידי Gemini.
כדי להשתמש שוב במטא-נתונים מהמשימה באצווה, כך שהשאילתה תפתור את אותם אובייקטים, מוסיפים את הדגל --metadata-gcs-uri. מידע נוסף מופיע במאמר תרגום שאילתה ל-GoogleSQL.
פתרון בעיות בתרגום
בקטעים הבאים מתוארות שגיאות נפוצות שמתרחשות כשמשתמשים במתרגם SQL באצווה.
בעיות בתרגום של RelationNotFound או AttributeNotFound
אחרי שמתרגמים שאילתה באמצעות המתרגם של SQL באצווה, יכול להיות שהתרגום ייכשל ותופיע השגיאה RelationNotFound או AttributeNotFound.
כדי למצוא תרגומים שנכשלו, נכנסים לדף Translation details ב-BigQuery במסוף Google Cloud ופותחים את הכרטיסייה הודעות ביומן.
התרגום פועל בצורה הטובה ביותר עם DDL של מטא-נתונים. אם לא נמצאות הגדרות של אובייקטים ב-SQL, מנוע התרגום מעלה בעיות מסוג RelationNotFound או AttributeNotFound. כדי לוודא שכל הגדרות האובייקטים קיימות, מומלץ להשתמש בכלי לחילוץ מטא-נתונים כדי ליצור חבילות מטא-נתונים. הוספת מטא-נתונים היא השלב הראשון שמומלץ לבצע כדי לפתור את רוב שגיאות התרגום, כי השלב הזה בדרך כלל מתקן הרבה שגיאות אחרות שנגרמות באופן עקיף בגלל מחסור במטא-נתונים.
מידע נוסף זמין במאמר יצירת מטא-נתונים לתרגום ולהערכה.
פתרון בעיות בתרגום באמצעות Gemini
כדי לתקן משימות תרגום שנכשלו עם השגיאות RelationNotFound או AttributeNotFound, אתם יכולים גם להשתמש ב-Gemini:
- עוברים לדף Translation details ופותחים את הכרטיסייה Log Messages.
- לוחצים על השאילתה שמופיעה בה ההודעה
RelationNotFoundאוAttributeNotFoundבעמודה קטגוריה. כדי לעבור לקובץ ולשורה שמכילים את השגיאה בכרטיסייה Code, לוחצים על
הודעת שגיאה.
בעמודה פעולה, לוחצים על הצעה לתיקון.
בוחרים באחת מהאפשרויות הבאות, החלה או החלה והפעלה מחדש:
- כדי להעתיק את קובץ הסכימה שנוצר מספריית הפלט לספריית הקלט, לוחצים על Apply.
- כדי להעתיק את קובץ הסכימה שנוצר מספריית הפלט לספריית הקלט ולפתוח חלון להרצה מחדש, לוחצים על Apply and rerun.
מכסות ומגבלות
- המכסות של BigQuery Migration API חלות.
- בכל פרויקט יכולות להיות עד 10 משימות תרגום פעילות.
- אין הגבלה על המספר הכולל של קובצי המקור והמטא-נתונים, אבל מומלץ לשמור על מספר קבצים נמוך מ-1,000 כדי לשפר את הביצועים.
תמחור
השימוש בכלי לתרגום SQL באצווה הוא בחינם. עם זאת, האחסון של קובצי הקלט והפלט כרוך בעמלות הרגילות. למידע נוסף, ראו תמחור של Storage.
תהליכי עבודה חלופיים להעברה באמצעות כלי שורת הפקודה
אפשר גם לשלוח משימת תרגום באצווה באמצעות קובץ תצורה עם Google Cloud CLI (gcloud bq migration-workflows) או עם כלי שורת הפקודה של BigQuery.
השלבים האלה מבוססים על ההנחה שהעליתם קובצי מקור לקטגוריה של Cloud Storage.
יצירת קובץ תצורה לתרגום
קובץ תצורה של תרגום מגדיר את הנתיב לקובצי המקור, את יעד הפלט ואת הניבים של המקור והיעד של התרגום. אפשר לכתוב את הקובץ הזה ב-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" ] } } } }
שליחה וניהול של משימות תרגום
כדי לשלוח ולנהל את משימות התרגום, אתם יכולים להשתמש באחד מכלי שורת הפקודה הבאים.
gcloud
כדי ליצור משימת תרגום ולהריץ את תהליך העבודה, משתמשים בפקודה הבאה:
gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE
כדי ליצור ולהריץ את תהליך העבודה ולחזור מיד עם קישור לתהליך העבודה, מוסיפים את הדגל --async:
gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE --async
כדי להציג את רשימת משימות התרגום, משתמשים בפקודה הבאה:
gcloud bq migration-workflows list --location=LOCATION
כדי לראות את הפרטים של משימת תרגום ספציפית, משתמשים בפקודה הבאה:
gcloud bq migration-workflows describe projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID
מחליפים את מה שכתוב בשדות הבאים:
-
LOCATION: המיקום של הפרויקט ב- Google Cloud שמריץ את משימת התרגום הזו. -
CONFIG_FILE: הנתיב לקובץ התצורה של התרגום. -
PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו פועלת משימת התרגום הזו. -
WORKFLOW_ID: המזהה של משימת התרגום.
BQ
כדי להריץ את משימת התרגום, משתמשים בפקודה הבאה:
bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE
כדי להציג את כל משימות התרגום, משתמשים בפקודה הבאה:
bq ls --migration_workflow --location=LOCATION
כדי לראות פרטים על משימת תרגום ספציפית, משתמשים בפקודה הבאה:
bq show --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID
כדי להסיר משימת תרגום מהרשימה, משתמשים בפקודה הבאה:
bq rm --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID
מחליפים את מה שכתוב בשדות הבאים:
-
LOCATION: המיקום של הפרויקט ב- Google Cloud שמריץ את משימת התרגום הזו. -
CONFIG_FILE: הנתיב לקובץ התצורה של התרגום. -
PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו פועלת משימת התרגום הזו. -
WORKFLOW_ID: המזהה של משימת התרגום.
אחזור קובצי פלט
כדי להוריד את קובצי הפלט אחרי שהמשימה מסתיימת, משתמשים ב-gcloud storage cp כמו שמתואר בקטע אחזור קובצי הפלט. כדי לבדוק את המשימה במסוף Google Cloud , קראו את המאמר בדיקת פלט התרגום.
המאמרים הבאים
מידע נוסף על השלבים הבאים בהעברת מחסן נתונים:
- סקירה כללית על מיגרציה
- הערכת העברה
- סקירה כללית על סכימה והעברת נתונים
- Data pipelines
- תרגום SQL אינטראקטיבי
- שימוש בשרת MCP של BigQuery Migration Service
- אבטחת מידע ומשילות מידע
- כלי לאימות נתונים