החל מ-10 באפריל 2026, Dataplex Universal Catalog נקרא עכשיו Knowledge Catalog. השמות של ה-API, ספריית הלקוח, ה-CLI ו-IAM לא משתנים. מידע נוסף זמין במאמר הכרות עם קטלוג הידע של Google Cloud.

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

שימוש ב-Antigravity CLI כדי לבדוק את הקשר הנתונים

העשרת מטא-נתונים ב-Knowledge Catalog (לשעבר Dataplex Universal Catalog) מאפשרת לכם לספק הקשר של נתונים מובְנים, כדי שסוכני AI יוכלו לבסס את התשובות שלהם על מקורות מהימנים ומאושרים. במדריך הזה תצרפו היבטים מותאמים אישית לטבלאות לדוגמה ב-BigQuery, ותשתמשו ב-Antigravity CLI כדי לבדוק איך סוכן AI מיישם את כללי המשילות שלכם.

מטרות

פריסת אגם נתונים ריאליסטי בכמה רמות ב-BigQuery לצורך בדיקה.
לעצב ולרשום תבניות מטא-נתונים בהתאמה אישית (סוגי היבטים) ב-Knowledge Catalog כדי להבדיל בין מוצרי נתונים רשמיים לבין טבלאות גולמיות בארגז החול.
מאמתים את כללי משילות המידע ואת העיגון של סוכן ה-AI באמצעות Antigravity CLI‏ (agy).

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

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

בוחרים Google Cloud פרויקט למדריך הזה.
מוודאים שהחיוב מופעל בפרויקט.

כדי להשלים את המדריך הזה, אתם צריכים גם הבנה בסיסית ב-BigQuery וב-Knowledge Catalog.

הכנת הסביבה

במדריך הזה משתמשים ב-Google Cloud Shell, סביבה של שורת פקודה שפועלת בענן. ‫Antigravity CLI (agy) מותקן מראש ב- Google Cloud Shell.

במסוף Google Cloud , לוחצים על Activate Cloud Shell בסרגל הכלים שבפינה הימנית העליונה. יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו.
ב-Cloud Shell, מגדירים את המשתנים PROJECT_ID ו-REGION כך שכל הפקודות הבאות יטרגטו את הפרויקט הספציפי שלכם ב- Google Cloud .
```
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
```

מפעילים את שירותי Google Cloud הנדרשים.

gcloud services enable \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  dataplex.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com

משכפלים את Google Cloud המאגר DevRel Demos.

מורידים את קוד התשתית והסקריפטים מ-GitHub. כדי לשלוף רק את התיקייה הספציפית שצריך למדריך הזה, משתמשים ב-sparse checkout.

# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos

# Specify and download only the folder you need for this tutorial
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

פריסת אגם נתונים לדוגמה ב-BigQuery

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

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

הופכים את סקריפט ההגדרות לקובץ הפעלה ומריצים אותו. הפעולה הזו יוצרת שלושה מערכי נתונים ב-BigQuery‏ (finance_mart, ‏ marketing_prod, ‏ analyst_sandbox) ומאכלסת את הטבלאות שלהם בנתונים לדוגמה:

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

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

הגדרת סוג היבט בהתאמה אישית ב-Knowledge Catalog

עכשיו אתם מגדירים את הכללים של משילות המידע (data governance). כדי לעשות את זה ב-Knowledge Catalog, יוצרים סוג היבט, שהוא תבנית מטא-נתונים עם סוגים מוגדרים היטב שאפשר לעשות בה שימוש חוזר.

בקטע הזה תרשמו את התבנית באמצעות ה-CLI של gcloud כדי לראות איך היא מוגדרת.

בדיקת הסכימה של תבנית ההיבט

מציגים את התוכן של aspect_template.json כדי לראות את הגדרת הסכימה:

cat aspect_template.json

מוצג מבנה ה-JSON הבא:

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      "...": "..."
    }
  ]
}

שימו לב איך הסכימה הזו אוכפת סוגי נתונים מחמירים, כמו enum לרמת הקריטיות (GOLD_CRITICAL, ‏ SILVER_STANDARD, ‏ BRONZE_ADHOC) ו-bool ל-is_certified. כך המטא-נתונים נשארים מובְנים ובפורמט קריא למכונה.

רישום סוג ההיבט ב-Knowledge Catalog

מריצים את הפקודה הבאה של gcloud כדי לרשום את התבנית הזו במרשם של Knowledge Catalog:

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

הוספת היבטי פיקוח לטבלאות של אגם הנתונים

זהו שלב הנדסי קריטי. כרגע, הטבלאות finance_mart.fin_monthly_closing_internal ו-analyst_sandbox.tmp_data_dump_v2_final_real נראות זהות לסוכן ה-AI. הם פשוט אובייקטים עם עמודות.

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

יצירת המטענים הייעודיים (payloads) של המטא-נתונים של ההיבטים

מפתחות ההיבטים של Knowledge Catalog חייבים להיות ייחודיים ברמה הגלובלית (עם קידומת של מזהה הפרויקט). הסקריפט ./generate_payloads.sh יוצר באופן דינמי את קובצי המטא-נתונים של YAML:

chmod +x ./generate_payloads.sh
./generate_payloads.sh

הפעולה הזו יוצרת ספריית aspect_payloads/ שמכילה 4 קובצי YAML שמגדירים תרחישים שונים של משילות מידע (fin_internal.yaml, ‏ fin_public.yaml, ‏ mkt_realtime.yaml, ‏ sandbox.yaml).

צירוף היבטים לטבלאות ב-BigQuery

לפני שמריצים את הסקריפט, צריך לבדוק את הנתונים שמצרפים לטבלאות. מריצים את הפקודה הבאה כדי לראות את המטא-נתונים של הנתונים הפיננסיים הפנימיים:
```
cat aspect_payloads/fin_internal.yaml
```
קובץ ה-YAML מגדיר את ההקשר העסקי של הטבלה:
```
your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true
```
שימו לב איך זה מגדיר במפורש את ההקשר העסקי, כמו הגדרת is_certified: true והקצאת הרמה GOLD_CRITICAL. כך סוכן ה-AI מקבל כללים ברורים ומובנים להערכה, במקום לנחש על סמך שמות הטבלאות.
מריצים את הסקריפט של האפליקציה. הסקריפט הזה עובר על הטבלאות ב-BigQuery ומשתמש בפקודה gcloud dataplex entries update כדי לצרף את המטא-נתונים לכל טבלה:
```
chmod +x ./apply_governance.sh
./apply_governance.sh
```

איך בודקים את ההיבטים שהוחלו במסוף Google Cloud

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

פותחים את הדף Knowledge Catalog במסוף Google Cloud . אפשר להשתמש בסרגל החיפוש העליון כדי למצוא אותו.
מחפשים את fin_monthly_closing_internal. כדי לפתוח את דף הפרטים של הטבלה ב-BigQuery, לוחצים על השם שלה בתוצאות.
בקטע תגים והיבטים אופציונליים שבתחתית הדף, מחפשים את ההיבט official-data-product-spec. מוודאים שהערכים תואמים לתרחיש "Gold Internal" שהחלתם.

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

בדיקת הקשר הנתונים באמצעות Antigravity CLI

לפני שאתם מפתחים אפליקציה, אתם יכולים לאמת את הלוגיקה של משילות המידע באופן מקומי באמצעות Antigravity CLI. כדי לעשות את זה, מתקינים את הפלאגין Knowledge Catalog ומגדירים את המיומנות של הנציג.

התקנת הפלאגין של Knowledge Catalog

ב-Cloud Shell, מתקינים את הפלאגין של השירות:

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

בדיקת ההגדרה של מיומנות הסוכן

הסקיל של הנציג הוא קובץ הגדרה סטטי שאפשר להשתמש בו שוב ושוב, והוא נמצא ב-.agents/skills/knowledge-catalog-governance/SKILL.md. הוא מכיל את הלוגיקה שמתרגמת כללים אנושיים מופשטים כמו "אני צריך נתונים בטוחים" לחיפושים טכניים מובְנים.

כדי לבדוק את הגדרת המיומנות ולהבין איך הקשר הנתונים פועל, בודקים את הקובץ SKILL.md:

cat .agents/skills/knowledge-catalog-governance/SKILL.md

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

התחלת הסשן ב-Antigravity CLI

מתחילים את הסשן ב-Antigravity CLI. מכיוון שאתם נמצאים בתיקיית הפרויקט, ה-CLI מגלה וטוען באופן אוטומטי את המיומנות מהספרייה .agents/skills:

agy

אימות ההתקנה של הפלאגין ב-CLI

ב-Antigravity CLI, מוודאים שהפלאגין פעיל. מקלידים /mcp כדי להציג רשימה של הכלים והפלאגינים שהוגדרו:

/mcp

בפלט אמור להופיע knowledge-catalog כפלאגין פעיל עם הכלים הזמינים שלו:

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

הרצת תרחישים לאימות הקשר הנתונים

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

תרחיש 1: אחזור נתונים מרמת הזהב של ההסמכה

בודקים אם Antigravity CLI יכול למצוא את הנתונים הכי מהימנים לישיבת דירקטוריון חשובה:

We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?

ממשק ה-CLI אמור לדלג על הנתונים הגולמיים ולמצוא את fin_monthly_closing_internal. כדי לעשות את זה, המערכת מתאימה את הבקשה שלכם לנתונים "סופיים" ו "סודיים" לתגי GOLD_CRITICAL ו-INTERNAL_ONLY שהחלתם קודם.

תרחיש 2: הגבלת השליפה לנתונים שאושרו חיצונית

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

I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?

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

תרחיש 3: אחזור נתונים בסטרימינג בזמן אמת

מדעני נתונים צריכים לעיתים קרובות את המידע העדכני ביותר. בודקים אם Antigravity CLI מבין את ההבדל בין אצווה יומית לבין שידור חי:

My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?

ה-CLI אמור למצוא את mkt_realtime_campaign_performance. הוא מזהה את תדירות העדכון של REALTIME_STREAMING במטא-נתונים.

תרחיש 4: בדיקת נתונים בארגז חול (sandbox) לא מאושר

לפעמים "טוב מספיק" עדיף על "מושלם". בודקים אם Antigravity CLI יכול למצוא את הנתונים הגולמיים של ארגז החול בשביל עבודה ניסיונית ב-ML:

I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.

ה-CLI אמור למצוא את tmp_data_dump_v2_final_real. הוא יודע שזו הבחירה הנכונה כי היא תואמת לרמה BRONZE_ADHOC ומסומנת במפורש ב-is_certified: false.

בסיום הבדיקה, אפשר לצאת מהסשן של ה-CLI:

/quit

הסרת המשאבים

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

אם אתם בסשן של Antigravity CLI, צאו ממנו בלחיצה כפולה על Ctrl+C או בהקלדה של /quit.
מריצים את סקריפט הניקוי כדי להשמיד את הטבלאות, מערכי הנתונים וסוגי ההיבטים של Knowledge Catalog ב-BigQuery שנוצרו במדריך הזה:
```
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
```
מסירים את הפלאגין של השירות ואת קובצי ההדגמה המקומיים:
```
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos
```

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

תרחישים לדוגמה נוספים של Knowledge Catalog