שימוש בתבניות של שאילתות

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

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

מגבלות

לתבניות של שאילתות יש את המגבלות הבאות:

  • תבניות של שאילתות תומכות בשתי הפניות לנתונים לכל היותר – כלומר, הנתונים שמשמשים להגדרת השאילתה של ה-TVF והקלט של פרמטר הנתונים שה-TVF מקבל. אפשר להפנות לכמה טבלאות או תצוגות בהגדרת השאילתה של ה-TVF, אבל כולן צריכות להיות שייכות לאותו בעלים או גורם של הנתונים.
  • פונקציות TVF של תבניות שאילתות תומכות רק בסוגים הקבועים TABLE ו-VIEW.
  • ההגדרות של תבניות השאילתות כפופות לאותן מגבלות כמו של פונקציות TVF.

תפקידים

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

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

כדי להפעיל את Analytics Hub API בפרויקט ב- Google Cloud , בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. נכנסים לדף Analytics Hub API במסוף Google Cloud .

    מעבר אל Analytics Hub API

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את הפרויקט.

  3. אם ה-API לא פועל, לוחצים על Enable.

gcloud

מריצים את הפקודה gcloud services enable:

gcloud services enable analyticshub.googleapis.com

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

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

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

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

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

כדי לבצע את המשימות שבמסמך הזה, נדרשות ההרשאות הבאות:

  • יצירה או מחיקה של TVF בחדר נקי לנתונים:
    • bigquery.routines.create בפרויקט
    • bigquery.routines.update בפרויקט
    • bigquery.routines.delete בפרויקט
  • נותנים הרשאה ל-TVF: bigquery.datasets.update במערכי הנתונים שאליהם השגרה ניגשת
  • יוצרים תבנית שאילתה:
    • analyticshub.listings.subscribe בפרויקט
    • analyticshub.queryTemplates.create בפרויקט
  • אישור תבנית של שאילתה:
    • bigquery.routines.create בפרויקט
    • bigquery.datasets.update במערכי הנתונים שהשגרה ניגשת אליהם
    • analyticshub.listings.create בפרויקט
    • analyticshub.queryTemplates.approve בפרויקט
  • עדכון של תבנית שאילתה קיימת: analyticshub.queryTemplates.update בתבנית השאילתה
  • אחזור פרטים של תבנית שאילתה: analyticshub.queryTemplates.get בתבנית השאילתה
  • הצגת רשימה של כל תבניות השאילתות בחילופי נתונים: analyticshub.queryTemplates.list בחילופי הנתונים
  • מחיקת תבנית שאילתה: analyticshub.queryTemplates.delete בתבנית השאילתה

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

תהליכי עבודה של יוצרי תבניות

כיוצרים של תבניות שאילתות, אתם יכולים:

הוספת כרטיס מוצר לחדר נקי לנתונים

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

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

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

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

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

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

  5. מגדירים את אמצעי הבקרה של המטא-נתונים של דף האפליקציה בחנות. אם רוצים לשתף רק את הסכימות והתיאורים של הנתונים שנוספו בשלב הקודם (ולא את הנתונים המשותפים עצמם), בוחרים באפשרות Exclude access to listing from linked dataset.

  6. בודקים את פרטי דף האפליקציה.

  7. לוחצים על הוספת נתונים. עכשיו ה-Clean Room כולל את המטא-נתונים של התצוגה שיצרתם לנתונים.

הוספת פונקציית TVF קיימת לחדר נקי לנתונים

אתם יכולים להוסיף TVF קיים לחדר נקי לנתונים באמצעות Analytics Hub API.

משתמשים בשיטה projects.locations.dataExchanges.listings.create.

בדוגמה הבאה מוסבר איך להפעיל את השיטה projects.locations.dataExchanges.listings.create באמצעות הפקודה curl:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/listings?listingId=LISTING_ID -d \
    '{"bigqueryDataset":{"dataset":"projects/PROJECT_ID/datasets/DATASET_ID","selectedResources":[{"routine":"projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID"}]},"displayName":"LISTING_NAME"}'

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

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
  • ‫LISTING_ID: מזהה דף האפליקציה.
  • ‫PROJECT_ID: מזהה הפרויקט שמכיל את מערך הנתונים של המקור.
  • ‫DATASET_ID: המזהה של מערך הנתונים המקורי.
  • ‫ROUTINE_ID: מזהה התרחיש.
  • ‫LISTING_NAME: השם המוצג של דף האפליקציה.

יצירת תבנית שאילתה

כדי ליצור תבנית שאילתה, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

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

  3. בחדר הנקי, עוברים לכרטיסייה Templates (תבניות).

  4. לוחצים על יצירת תבנית.

  5. מזינים שם תצוגה ותיאור לתבנית.

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

  7. מציעים הגדרת שאילתה באמצעות הסכימות של התצוגות שנוספו ל-Clean Room:

    • מגדירים את השאילתה באמצעות תחביר CREATE TABLE FUNCTION נתמך.

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

          query_template1(t1 TABLE<year INT64>) AS (SELECT * FROM `project_id.dataset_id.table_id` WHERE year = table_id.year)

    • אם החלתם כללים של ניתוח פרטיות על הנתונים, ודאו שה-TVF הזה כולל תחביר SQL ספציפי לפרטיות, כמו SELECT WITH AGGREGATION_THRESHOLD.

  8. בודקים את פרטי התבנית.

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

אתם יכולים לעדכן את תבנית השאילתה או לשלוח את תבנית השאילתה לבדיקה.

API

בדוגמה הבאה מוסבר איך ליצור תבנית שאילתה באמצעות הפקודה curl:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates?queryTemplateId=QUERY_TEMPLATE_ID -d \
'{
  "displayName": "DISPLAY_NAME",
  "routine": {
    "routineType": "TABLE_VALUED_FUNCTION",
    "definitionBody": "QUERY_TEMPLATE_ID(TVF arguments) AS (TVF_DEFINITION)"
  }
}'

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

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.
  • ‫DISPLAY_NAME: השם המוצג של תבנית השאילתה. אי אפשר לעדכן את השם המוצג של תבנית השאילתה אחרי שיוצרים אותה.
  • ‫TVF_DEFINITION: הגדרת ה-TVF.

בדוגמת הקוד הבאה מוצגת דוגמה ל-definition_body לקריאה ל-API. צריך להגדיר את ההפניה המלאה לנתיב הטבלה, כולל מזהה הפרויקט ומזהה מערך הנתונים, מהנתונים שנוספו ל-Clean Room:

  query_template1(t1 TABLE<year INT64>) AS (SELECT * FROM `project_id.dataset_id.table_id` WHERE year = table_id.year)

ה-definition_body דומה להגדרה של שגרה. הקוד הקודם של definition_body מתורגם לשגרה הבאה:

  CREATE OR REPLACE TABLE FUNCTION APPROVERS_DATASET.query_template1(t1 TABLE, y INT64)
  AS (SELECT * FROM t1 WHERE year > y)

מחליפים את APPROVERS_DATASET במזהה של קבוצת הנתונים שבה מי שמאשר התבנית יוצר את התרחיש.

אתם יכולים לעדכן את תבנית השאילתה או לשלוח את תבנית השאילתה לבדיקה.

עדכון של תבנית שאילתה

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

כדי לעדכן תבנית של שאילתה, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

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

  3. בחדר הנקי, עוברים לכרטיסייה Templates (תבניות).

  4. בשורה של התבנית שרוצים לעדכן, לוחצים על פעולות > עריכת התבנית.

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

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

  7. בודקים את פרטי התבנית.

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

API

בדוגמה הבאה מוסבר איך לעדכן תבנית של שאילתה באמצעות הפקודה curl:

 curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H 'x-goog-user-project:DCR_PROJECT_ID' \
 -X PATCH "https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID?updateMask=description" \
 -d '{
   "description": "New query template"
 }'

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

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

שליחת תבנית שאילתה לבדיקה

כדי לשלוח תבנית של שאילתה לבדיקה, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

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

  3. בחדר הנקי, עוברים לכרטיסייה Templates (תבניות).

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

API

בדוגמה הבאה מוסבר איך לשלוח תבנית שאילתה לבדיקה באמצעות הפקודה curl:

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID:submit

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

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

מחיקת תבנית של שאילתה

אפשר למחוק תבנית של שאילתה רק אם היא בסטטוס DRAFT. אחרי ששולחים תבנית שאילתה לבדיקה, אי אפשר למחוק אותה.

כדי למחוק תבנית שאילתה, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

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

  3. בחדר הנקי, עוברים לכרטיסייה Templates (תבניות).

  4. בשורה של התבנית שרוצים למחוק, לוחצים על פעולות > מחיקת התבנית.

API

בדוגמה הבאה מוסבר איך למחוק תבנית של שאילתה באמצעות הפקודה curl:

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X DELETE https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID

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

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

תהליכי עבודה של אישור תבניות

אם יש לכם הרשאה לאשר תבניות של שאילתות, אתם יכולים לאשר תבנית של שאילתה.

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

אישור תבנית שאילתה

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

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

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

  3. בחדר הנקי, עוברים לכרטיסייה Templates (תבניות).

  4. בשורה של התבנית שצריך לבדוק, לוחצים על סטטוס אישור > נדרשת בדיקה.

  5. לוחצים על אישור.

  6. בוחרים את המיקום של התבנית. זה המיקום שבו נוצרת פונקציית ה-TVF לשיתוף.

  7. בודקים את תבנית השאילתה המוצעת.

  8. כדי לאשר את תבנית השאילתה לשימוש בחדר הנקי לנתונים, לוחצים על Approve.

API

  1. יוצרים את השגרה מתבנית השאילתה באמצעות קריאה ל-method jobs.query:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://bigquery.googleapis.com/bigquery/v2/projects/ROUTINE_PROJECT_ID/queries --data '{"query":"ROUTINE_CREATION_QUERY","useLegacySql":false}'

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

    • ‫ROUTINE_PROJECT_ID: מזהה הפרויקט שבו נוצרה השגרה.
    • ‫ROUTINE_CREATION_QUERY: השאילתה ליצירת השגרה.

  2. מוסיפים את השגרה שיצרתם לחדר הנקי לנתונים:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/listings?listingId=LISTING_ID -d \
'{"bigqueryDataset":{"dataset":"projects/PROJECT_ID/datasets/DATASET_ID","selectedResources":[{"routine":"projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID"}]},"displayName":"LISTING_NAME"}'

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

    • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
    • ‫LOCATION: המיקום של החדר הנקי לנתונים.
    • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
    • ‫LISTING_ID: מזהה דף האפליקציה.
    • ‫PROJECT_ID: מזהה הפרויקט שמכיל את מערך הנתונים של המקור.
    • ‫DATASET_ID: המזהה של מערך הנתונים המקורי.
    • ‫ROUTINE_ID: מזהה התרחיש.
    • ‫LISTING_NAME: השם המוצג של דף האפליקציה.

  3. מעדכנים את הסטטוס של תבנית השאילתה ל-APPROVED:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID:approve  --data '{}'

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

    • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
    • ‫LOCATION: המיקום של החדר הנקי לנתונים.
    • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
    • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

דחיית תבנית שאילתה

במסוף Google Cloud , אתם יכולים לדחות תבנית שאילתה על ידי אי-אישור של תבנית השאילתה שנשלחה לבדיקה.

תהליכי עבודה של תבניות למנויים

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

הרשמה לתבנית שאילתה

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

המסוף

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

אחרי שנרשמים לחדר הנקי לנתונים, פועלים לפי השלבים הבאים כדי להריץ תבנית שאילתה:

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

    כניסה ל-BigQuery

  2. בחלונית Explorer, עוברים למערך הנתונים המקושר שיצרתם כשנרשמתם ל-Clean Room.

  3. פותחים את השגרה או את ה-TVF שמשותפים במערך הנתונים המקושר.

  4. לוחצים על Invoke table function.

  5. מחליפים את הפרמטר בקלט המקובל, שהוא שם הטבלה או שדה.

  6. לוחצים על Run.

אם אתם לא יכולים לראות את ה-TVF בתור רכיב צאצא של מערך הנתונים המקושר בחלונית Explorer, אתם יכולים לשלוח שאילתה ל-TVF ישירות במערך הנתונים המקושר:

SELECT * FROM `my_project.dcr_linked_dataset.mytvf`(TABLE myTable);

API

משתמשים בשיטה projects.locations.dataExchanges.subscribe.

בדוגמה הבאה מוסבר איך להפעיל את השיטה projects.locations.dataExchanges.subscribe באמצעות הפקודה curl:

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID:subscribe  --data '{"destination":"projects/SUBSCRIBER_PROJECT_ID/locations/LOCATION","subscription":"SUBSCRIPTION"}'

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

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של חדר נקי לנתונים.
  • ‫SUBSCRIBER_PROJECT_ID: מזהה הפרויקט של הפרויקט המנוי לתבנית.
  • ‫SUBSCRIPTION: שם המינוי.

אחרי שנרשמים לתבנית השאילתה, אפשר לשלוח שאילתה ל-TVF ישירות במערך הנתונים המקושר:

SELECT * FROM `my_project.dcr_linked_dataset.mytvf`(TABLE myTable);

תרחישים לדוגמה

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

תרחיש של שיתוף בכיוון אחד

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

בתרחיש הזה, משתמש א' הוא הבעלים של חדר נקי לנתונים. הוא יוצר חדר נקי לנתונים בשם campaign_analysis ומוסיף קבוצת נתונים בשם my_campaign עם טבלה בשם campaigns. משתמש א' מגדיר מדיניות של סף לצבירת נתונים ואמצעי בקרה על מטא-נתונים, כך שרק סכימת המטא-נתונים גלויה ולמנויי התבנית אין גישה לנתוני המקור. לאחר מכן, משתמש א' יוצר תבנית שאילתה על ידי הגדרת TVF מהטבלה campaigns, ומגביל את המנויים של מערך הנתונים המקושר להרצת ה-TVF בלבד.

זה התחביר של TVF:

campaigns_template(t1 TABLE<campaign_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM my_project.my_campaign.campaigns
group by company_id, company
);

למשתמש א' יש את ההרשאות המתאימות לטבלה campaigns עם התפקיד "בעלים של נתונים ב-BigQuery", ולכן הוא יכול לאשר בעצמו את תבנית השאילתה מיד אחרי שהוא שולח אותה לבדיקה.

שיתוף פעולה עם כמה משתמשים

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

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

זה התחביר של TVF:

campaigns_template(t1 TABLE<campaign_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM my_project.my_campaign.campaigns
group by company_id, company
);

מכיוון שמשתמש ב' לא הוסיף את הטבלה campaigns או שהיא לא בבעלותו, רק משתמש א' יכול לאשר את תבנית השאילתה אחרי שהיא נשלחת לבדיקה. כדי להשתמש בתבנית השאילתה, משתמש ב' צריך להירשם ל-Clean Room ולהפעיל את ה-TVF. משתמש ב' מעביר טבלה משלו עם שדה בשם campaign_ID כפרמטר של הטבלה, והוא יכול להריץ את ה-SQL שמתמקד בפרטיות ומוגדר בתבנית השאילתה. משתמש ב' לא צריך להוסיף את הנתונים שלו לחדר הנקי.

משתמש ב' מוסיף גם הוא מערך נתונים בשם my_transactions לחדר הנקי, שכולל טבלה בשם transactions וטבלה בשם products. משתמש ב' מגדיר מדיניות של סף לצבירת נתונים ואמצעי בקרה על מטא-נתונים, כך שרק סכימת המטא-נתונים גלויה ולמנויי התבנית אין גישה לנתוני המקור.

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

transactions_template(t1 TABLE<user_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, campaign_id, sku, category, date, sum(amount) FROM my_project.my_transactions.transactions
group by company_id, company, campaign_id, sku, category, date
);

transactions_template_with_join(t1 TABLE<user_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category, sum(t.amount) FROM my_project.my_transactions.transactions t
left join my_project.my_transactions.products p
on t.product_id = p.product_id
group by t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category
);

מכיוון שמשתמש א' לא הוסיף את הטבלאות transactions ו-products והן לא בבעלותו, רק משתמש ב' יכול לאשר את תבנית השאילתה אחרי שהיא נשלחת לבדיקה. כדי להשתמש בתבנית השאילתה, משתמש א' צריך להירשם ל-Clean Room ולהפעיל את ה-TVF. משתמש א' מעביר טבלה משלו עם שדה בשם user_ID כפרמטר הטבלה, והוא יכול להריץ את ה-SQL שמתמקד בפרטיות ומוגדר בתבנית השאילתה. משתמש א' לא צריך להוסיף את הנתונים שלו ל-Clean Room.

תמחור

בטבלה הבאה מפורטים המחירים של תבניות השאילתות בחדר הנקי לנתונים ב-BigQuery:

תפקיד פרטי התמחור
תורם נתונים החיוב הוא רק על אחסון הנתונים.
מנוי לתבנית החיוב הוא רק על העיבוד (ניתוח) בזמן הרצת השאילתות.

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