‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

הפעלת תרגומים של SQL

מפעילים את ה-API הנדרש ומקבלים את ההרשאות שדרושות לשימוש בכלי לתרגום SQL ב-BigQuery. למידע נוסף, ראה הפעלת תרגומי SQL.

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

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

צפייה במשימות העברה ומעקב אחריהן: צפייה ב-MigrationWorkflow (roles/bigquerymigration.viewer)
שליחת משימות העברה: MigrationWorkflow Editor (roles/bigquerymigration.editor)
גישה לקטגוריות של Cloud Storage לקלט ולקבצים: Storage Object Admin‏ (roles/storage.objectAdmin) – בקטגוריית המקור ובקטגוריית היעד של Cloud Storage.

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

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

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

כדי ליצור משימות תרגום באמצעות כלי התרגום האינטראקטיבי, Translator 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

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

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

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

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

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

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

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

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

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

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

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

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

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

אפשר גם ליצור ולהשתמש בקבצי YAML של הגדרות כדי להתאים אישית את התרגומים של קבוצות קבצים. אפשר להשתמש בקבצים האלה כדי לשנות את פלט התרגום בדרכים שונות. לדוגמה, ניתן ליצור קובץ YAML לתצורה כדי לשנות את רישיות האותיות (case) של אובייקט 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 שלא נתמכות באמצעות פונקציות UDF מסייעות

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

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

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

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

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

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

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

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

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

המסוף

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

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

מעבר אל SQL Translation
בחלונית תרגום SQL, לחץ על התחל תרגום.
בקטע הגדרת תרגום, מזינים את הפרטים הבאים:
1. בשדה שם התצוגה, מקלידים שם לעבודת התרגום. השם יכול להכיל אותיות, מספרים או קווים תחתונים.
2. בקטע מיקום העיבוד, בוחרים את המיקום שבו רוצים להריץ את עבודת התרגום. לדוגמה, אם אתם נמצאים באירופה ואינכם רוצים שהנתונים שלכם יחצו גבולות מיקום כלשהם, בחרו את האזור eu. כדי לקבל את התוצאות הכי טובות, מומלץ לבחור את אותו מיקום של דלי קובץ המקור.
3. בשדה Source dialect (ניב המקור), בוחרים את ניב ה-SQL שרוצים לתרגם.
4. בקטע Target dialect (ניב היעד), בוחרים באפשרות GoogleSQL.
לוחצים על הבא.
עבור פרטי מיקום הקובץ, ציין את נתיבי אחסון הענן לשימוש עבור קלט ופלט של תרגום. אפשר להקליד את הנתיבים בפורמט bucket_name/folder_name/ או להשתמש באפשרות עיון כדי לנווט לתיקייה.
1. בקטע מיקום ספריית הפלט, מציינים נתיב לתיקיית היעד ב-Cloud Storage של הקבצים המתורגמים. זה משמש כתיקיית שורש לכל פלט התרגום.
2. בחר מיקום ספריית קלט אחד או יותר המכילים את הנתיב לקבצי ה-SQL לתרגום.
3. אם צריך, אפשר לתת לכל ספריית קלט שם של ספריית פלט משנית מתחת לספריית הפלט הראשית.
לוחצים על הבא.
בוחרים את ההגדרות האופציונליות שרוצים להתאים אישית את המטא-נתונים ואת פלט התרגום הנוסף.
ניתן להתאים אישית עוד יותר את התנהגות התרגום על ידי יצירת קבצי YAML לתצורה והצבת קבצים אלה בדלי אחסון הענן של הקלט. אפשר להשתמש בקבצים האלה כדי להגדיר שינוי שם של אובייקטים, להפעיל אופטימיזציות, לשפר תרגומים באמצעות Gemini ועוד. למידע נוסף על קבצי YAML לתצורה, ראה יצירת קובץ YAML לתצורה.
לחץ על צור כדי להתחיל את עבודת התרגום.

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

לקוח לתרגום קבוצתי

התקינו את לקוח תרגום האצווה ואת ממשק שורת הפקודה (CLI) של גוגל בענן.
יצירת קובץ פרטי גישה של ממשק שורת פקודה (CLI) ב-gcloud.
בספריית ההתקנה של לקוח התרגום באצווה, משתמשים בעורך הטקסט שבחרתם כדי לפתוח את הקובץ config.yaml ולשנות את ההגדרות הבאות:
- project_number: הקלד את מספר הפרויקט שברצונך להשתמש בו עבור משימת התרגום הקבוצתית. אפשר לראות את מספר הפרויקט בחלונית Project info בGoogle Cloud דף הפתיחה של המסוף.
- ‫gcs_bucket: מקלידים את השם של קטגוריית Cloud Storage שבה לקוח התרגום באצווה משתמש כדי לאחסן קבצים במהלך העיבוד של עבודת התרגום.
- ‫input_directory: מקלידים את הנתיב המוחלט או היחסי לספרייה שמכילה את קובצי המקור וקובצי המטא-נתונים.
- output_directory: הקלד את הנתיב המוחלט או היחסי לתיקיית היעד עבור הקבצים המתורגמים.
שומרים את השינויים וסוגרים את הקובץ config.yaml.
מקם את קבצי המקור והמטא-דאטה שלך בתיקיית הקלט.
מריצים את לקוח התרגום באצווה באמצעות הפקודה הבאה:
```
bin/dwh-migration-client
```
יוצרים עבודת תרגום.
- הדוגמה הבאה מציגה פקודה ליצירת משימת תרגום. הפקודה תפעיל את תהליך העבודה ותציג פלט אם תהליך העבודה יצליח.
```
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 .
זה שינוי אופציונלי. אחרי שמשימת התרגום מסתיימת, מוחקים את הקבצים שהמשימה יצרה בקטגוריה של Cloud Storage שציינתם, כדי להימנע מעלויות אחסון.

BigQuery CLI

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

יוצרים קובץ הגדרות תרגום בפורמט 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"
      ]
    }
  }
}
}

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

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

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

מעבר אל SQL Translation
ברשימת עבודות התרגום, אתר את המשימה שעבורה ברצונך לראות את פרטי התרגום. לאחר מכן לוחצים על שם עבודת התרגום. תוכלו לראות תרשים סנקיי שממחיש את האיכות הכוללת של העבודה, את מספר שורות הקוד של הקלט (לא כולל שורות ריקות והערות) ואת רשימת הבעיות שהתרחשו במהלך תהליך התרגום. חשוב לתת עדיפות לתיקונים משמאל לימין. בעיות בשלב מוקדם עלולות לגרום לבעיות נוספות בשלבים הבאים.
החזק את המצביע מעל סרגלי השגיאה או האזהרה, ועיין בהצעות כדי לקבוע את השלבים הבאים לאיתור באגים במשימת התרגום.
בחר בכרטיסייה סיכום יומן רישום כדי לראות סיכום של בעיות התרגום, כולל קטגוריות בעיות, פעולות מוצעות ותדירות התרחשות כל בעיה. אפשר ללחוץ על העמודות בתרשים סנקיי כדי לסנן בעיות. אפשר גם לבחור קטגוריית בעיות כדי לראות הודעות יומן שמשויכות לקטגוריית הבעיות הזו.
בוחרים בכרטיסייה הודעות יומן כדי לראות פרטים נוספים על כל בעיה בתרגום, כולל קטגוריית הבעיה, הודעת הבעיה הספציפית וקישור לקובץ שבו הבעיה התרחשה. ניתן ללחוץ על סרגלי ההדמיה של Sankey כדי לסנן בעיות. אפשר לבחור בעיה בכרטיסייה Log Message כדי לפתוח את Code tab שבו מוצגים קובץ הקלט וקובץ הפלט, אם רלוונטי.
לוחצים על הכרטיסייה Job details כדי לראות את פרטי ההגדרה של עבודת התרגום.

דוח סיכום

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

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

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

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

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

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

לשונית קוד

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

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

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

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

כרטיסיית תצורה

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

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

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

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

מעיינים בכרטיסייה 'הגדרה' בדף התרגום ל-SQL.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מגבלות

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

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

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

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

למידע נוסף, ראו יצירת מטא-נתונים לתרגום והערכה.

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

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

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

תמחור

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

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

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

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

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

הפעלת תרגומים של SQL

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

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

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

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

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

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

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

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

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

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

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

המסוף

לקוח לתרגום קבוצתי

BigQuery CLI

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

Google Cloud פלט בקונסולה

דוח סיכום

לשונית קוד

כרטיסיית תצורה

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

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

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

מגבלות

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

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

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

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

תמחור

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

בעיות תרגום של `RelationNotFound` או `AttributeNotFound`