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

הרצת אלגוריתמים של Spanner Graph

במאמר הזה מוסבר איך להריץ אלגוריתמים ב-Spanner Graph.

מבנה שאילתת האלגוריתם של Spanner Graph

המבנה של שאילתת אלגוריתם ב-Spanner Graph:

EXPORT DATA OPTIONS (export_option_list) AS
GRAPH graph_name
match_clause
call_statement algorithm_name(common_input, algorithm_specific_input)
  YIELD algorithm_specific_output
RETURN results

‫export_option_list: אפשרויות שמגדירות איך לשמור את תוצאות השאילתה של האלגוריתם. מידע נוסף זמין במאמרים בנושא אפשרויות Cloud Storage ואפשרויות Spanner.
‫graph_name: שם התרשים.
‫match_clause: הצהרות MATCH אופציונליות להגדרת רכיבי קלט של אלגוריתם.
‫call_statement: משתמשים בהצהרת CALL כשמשמיטים את המשתנה match_clause ורוצים לבצע פעולה על הגרף כולו. משתמשים בהצהרה CALL PER() כשהמשתנה match_clause קיים ורוצים לבצע פעולה בטבלת העבודה. מידע נוסף זמין במאמר GQL CALL.
‫algorithm_name: שם האלגוריתם שרוצים להריץ. לרשימת האלגוריתמים הזמינים, ראו האלגוריתמים של Spanner Graph.
‫common_input: פרמטרים של קלט עם שם שמשותפים לכל השאילתות של האלגוריתם. מידע נוסף זמין במאמר פרמטרים נפוצים של קלט אלגוריתם.
algorithm_specific_input: פרמטרים של קלט עם שם לאלגוריתם. מידע נוסף על פרמטרים של קלט מופיע במאמר אלגוריתמים של Spanner Graph.
‫algorithm_specific_output: הפלט של קריאת האלגוריתם. מידע נוסף זמין בפלטים שמוגדרים באלגוריתמים של Spanner Graph ובסעיף YIELD בהצהרת CALL.
‫results: מגדיר מה יוחזר בתוצאות השאילתה.

השאילתה מורכבת מהצהרת EXPORT DATA, שמגדירה איך לשמור את התוצאות, ומ-GRAPH CLAUSE שמפיק את תוצאת השאילתה של האלגוריתם.

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

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

השאילתה לא מחזירה נתונים. המשתנה export_option_list קובע איך התוצאות נשמרות.

למידע נוסף על שאילתות של אלגוריתמים ב-Spanner Graph, עיינו בקטעים הבאים במאמר הזה:

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

פרמטרים נפוצים של קלט אלגוריתם

מציינים את הפרמטרים האלה של קלט בעל שם בפורמט הבא: NAME => VALUE, ....

שם	סוג הערך	חובה	ערך ברירת המחדל	תיאור
`node_labels`	`ARRAY`	לא	(ללא)	נתמך רק כשמשתמשים ב-`CALL`. רשימה של תוויות צומת שצריך לכלול בקלט של האלגוריתם. אם מציינים תווית, נכללים רק צמתים עם תווית אחת לפחות שתואמת לתווית שצוינה.
`edge_labels`	`ARRAY`	לא	(ללא)	נתמך רק כשמשתמשים ב-`CALL`. רשימה של תוויות קצה שייכללו בקלט של האלגוריתם. אם צוין, רק קצוות עם לפחות תווית תואמת אחת נכללים.
`edge_weight_property`	`STRING`	לא	(ללא)	השם של מאפיין הקצה שמכיל את המשקלים. אם לא מגדירים משקל, המערכת מקצה משקל ברירת מחדל של 1 לכל הקצוות. סוג הערך של המאפיין חייב להיות מספרי.
`machine_category`	`STRING`	לא	ברירת מחדל	קטגוריית המכונה שבה יש להשתמש להרצת האלגוריתם. הערכים הנתמכים הם: `default`, ‏ `large`
`fallback_compute_region`	`STRING`	לא	(ללא)	אזור הגיבוי שבו מתבצעת ההפעלה של האלגוריתם אם יש מגבלות קיבולת באזור הבית. הוא חייב להיות באותה סמכות שיפוט כמו אזור הבית של המכונה של Spanner (לדוגמה, `us-central1` אם אזור הבית הוא `us-east1`).
`max_idle_time`	`STRING`	לא	‫30 מ'	מציין כמה זמן המכונה צריכה להישאר פעילה לשימוש חוזר אחרי שהאלגוריתם מסתיים. הפורמט הוא רצף של מספרים עשרוניים, שלכל אחד מהם יש סיומת של יחידה, כמו `4m`, `1.5h` או `1h45m`. יחידות הזמן התקינות הן `ns`, `us` (או `µs`), `ms`, `s`, `m`, `h`.

טיפול בפלט של האלגוריתם

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

שמירת התוצאות ב-Cloud Storage

כדי להשתמש באפשרות הזו, ודאו שהתפקיד אדמין של אובייקט אחסון (roles/storage.objectAdmin) מוקצה לחשבון השירות של Spanner service-PROJECT_NUMBER@gcp-sa-spanner. שמנוהל על ידי Google.

האפשרויות הבאות של EXPORT DATA נתמכות כששומרים תוצאות ב-Cloud Storage. מציינים את האפשרויות בפורמט הבא: NAME=VALUE, ....

שם	סוג הערך	חובה	תיאור
`uri`	`STRING`	כן	ה-URI של היעד לייצוא, בפורמט `gs://bucket/path/file`. אם אתם מייצאים כמות גדולה של נתונים, השתמשו בתו כללי לחיפוש ב-`uri` כדי לייצא נתונים למספר קבצים. לדוגמה, `gs://bucket/path/file_*.csv`.
`format`	`STRING`	כן	הפורמט של הנתונים המיוצאים. ערכים נתמכים: `CSV`, ‏ `PARQUET`, ‏ `AVRO`.
`header`	`BOOL`	לא	אם `true`, המערכת מדפיסה כותרות עמודות בשורה הראשונה של כל קובץ נתונים. ערך ברירת המחדל הוא `false`. המאפיין הזה רלוונטי רק לקובצי CSV.
`overwrite`	`BOOL`	לא	אם הערך הוא `true`, המערכת מחליפה את כל הקבצים הקיימים עם אותו URI. אחרת, אם קיימים קבצים עם אותו URI, ההצהרה מחזירה שגיאה. ערך ברירת המחדל הוא `false`.
`field_delimiter`	`STRING`	לא	התו שמפריד בין השדות. ברירת המחדל: `,` (פסיק). רלוונטי רק ל-CSV.
`compression`	`STRING`	לא	מציינים את פורמט הדחיסה. אם לא מציינים פורמט דחיסה, הקבצים לא נדחסים. בשביל `CSV`, הערך הנתמך הוא `GZIP`. בשביל `PARQUET`, הערכים הנתמכים הם: `SNAPPY`, ‏ `GZIP`, ‏ `ZSTD`. בשביל `AVRO`, הערכים הנתמכים הם: `DEFLATE`, `SNAPPY`.

שמות העמודות בסעיף RETURN מגדירים את שמות העמודות בקובצי הפלט של Cloud Storage.

ייצוא נתונים לקובץ אחד או יותר

שאילתות Spanner Graph תומכות באופרטור תו כללי אחד (*) ב-uri. התו הכללי לחיפוש יכול להופיע ברכיב של שם הקובץ, אבל לא בשם הקטגוריה, בשם התיקייה או בסיומת הקובץ. אם קבוצת התוצאות גדולה, שימוש באופרטור התו הכללי יורה ל-Spanner Graph ליצור כמה קבצים מחולקים על סמך התבנית שסיפקתם. המערכת מחליפה את האופרטור של התו הכללי במספר, החל מאפס, עם אפסים משמאל עד 12 ספרות. לדוגמה, URI של gs://my-bucket/file-*.csv יוצר קבצים כמו gs://my-bucket/file-000000000000.csv,‏ gs://my-bucket/file-000000000001.csv וקבצים דומים.

אם משתמשים ב-uri בלי תו כללי, התוצאה היא קובץ יחיד, כמו gs://my-bucket/file.csv.

סוגי הנתונים

כשמייצאים נתונים, סוגי הנתונים של הגרף ב-Spanner מומרים באופן הבא, בהתאם לפורמט:

CSV

כל סוגי הנתונים מומרים לייצוג המחרוזת שלהם:

ערכי BOOL מומרים ל-true או ל-false.
ערכי BYTES מקודדים ב-Base64.
הפורמט של ערכי TIMESTAMP הוא YYYY-MM-DD HH:MM:SS.ffffff UTC.
ערכי NULL מופיעים כמחרוזות ריקות.

אי אפשר לייצא נתונים מקוננים ונתונים שחוזרים על עצמם בפורמט CSV.

Avro

סוג הנתונים ב-Spanner	סוג הנתונים Avro
`BOOL`	`BOOLEAN`
`INT64`	`LONG`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`BYTES` עם סוג לוגי `DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTES`
`TIMESTAMP`	`LONG` (מיקרו-שניות מאז ראשית זמן יוניקס)
`NULL`	`null`

Parquet

סוג הנתונים ב-Spanner	סוג הנתונים ב-Parquet
`BOOL`	`BOOLEAN`
`INT64`	`INT64`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTE_ARRAY`
`TIMESTAMP`	`TIMESTAMP_MICROS`
`NULL`	`null`

שמירת התוצאות ב-Spanner

האפשרויות הבאות של EXPORT DATA נתמכות כששומרים את התוצאות במכונה המקורית של Spanner. מציינים את האפשרויות בפורמט הבא: NAME=VALUE, ....

שם	סוג הערך	חובה	תיאור
`format`	`STRING`	כן	הפורמט של הנתונים שמייצאים. חייב להיות `CLOUD_SPANNER`.
`table`	`STRING`	כן	שם טבלת היעד ב-Spanner שאליה ייכתבו התוצאות. זו יכולה להיות כל טבלה במכונה של Spanner.
`write_mode`	`STRING`	כן	מצב הכתיבה שבו רוצים להשתמש. הערכים הנתמכים הם: ‫`update_ignore_all`: עדכון של שורות קיימות בטבלת היעד. ‫`upsert_ignore_all`: הוספה של שורות חדשות או עדכון של שורות קיימות בטבלת היעד. בשני המצבים, Spanner מדלג על כל רשומה שגורמת להפרת אילוץ (לדוגמה, מפתחות חסרים בעדכון, הפרה של אינדקס ייחודי, הפרה של אילוץ מפתח זר). עם זאת, הכתיבה נכשלת בגלל שגיאות שלא קשורות להפרת אילוצים (לדוגמה, חוסר התאמה בסוג העמודה, ערכים חסרים בעמודות NOT NULL).

דרישות

כששומרים את תוצאות האלגוריתם בחזרה ב-Spanner, שאילתת האלגוריתם צריכה לעמוד בדרישות הבאות:

טבלת היעד חייבת להתקיים.
העמודות חייבות להיות קיימות עם סוג תואם: כל שמות העמודות שצוינו במשפט RETURN חייבים להיות קיימים כבר בטבלת היעד עם סוג נתונים תואם. אם צריך, משתמשים בכינויים כדי להתאים לשמות העמודות בטבלת היעד. לדוגמה: RETURN node.id AS person_id.
הכללה של כל העמודות של המפתח הראשי: סעיף RETURN חייב לכלול את כל העמודות של המפתח הראשי בטבלת היעד.

כתיבת סמנטיקה

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

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

המערכת כותבת את תוצאות האלגוריתם בחזרה ל-Spanner Graph באמצעות MEDIUM priority.

הרצת שאילתות אלגוריתם לדוגמה

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

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

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

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

מוסיפים עמודה חדשה בשם page_rank לטבלה Account. ‫Spanner כותב את תוצאות האלגוריתם בעמודה החדשה הזו. אחר כך מרעננים את הגדרת התרשים כדי שאפשר יהיה לגשת אל page_rank כמאפיין של צומת.

-- Add `page_rank` as a column. Data type of this column matches the data type defined in `PageRank` output signature.
ALTER TABLE Account ADD COLUMN page_rank FLOAT64;

-- Rerun the graph definition DDL to pickup `page_rank` as a new property.
CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (`Account`, `Person`)
  EDGE TABLES (
    `PersonOwnAccount`
      SOURCE KEY (id) REFERENCES `Person` (id)
      DESTINATION KEY (account_id) REFERENCES `Account` (id)
      LABEL `Owns`,
    `AccountTransferAccount`
      SOURCE KEY (id) REFERENCES `Account` (id)
      DESTINATION KEY (to_id) REFERENCES `Account` (id)
      LABEL `Transfers`
  );

הפעלת אלגוריתם על גרף מלא עם מסנן תוויות ושמירת התוצאות ב-Cloud Storage

בדוגמה הזו מריצים את ההצהרה PageRank כדי לדרג את החשבונות על סמך ההעברות שהם משתתפים בהן. תוצאות השאילתה נשמרות בקטגוריה של Cloud Storage בפורמט CSV בשם my-bucket-name/my-output.csv.

EXPORT DATA OPTIONS (
  uri = "gs://my-bucket-name/my-output.csv",
  format = "csv"
) AS
GRAPH FinGraph
CALL PageRank(node_labels => ['Account'], edge_labels => ['Transfers']) YIELD node, score
RETURN node.id, score AS page_rank

ב-Cloud Storage, אחרי שהשאילתה הזו תסתיים בהצלחה, אמור להופיע קובץ CSV עם שתי עמודות (id ו-page_rank).

הפעלת אלגוריתם על תת-גרף שמוגדר על ידי `MATCH` ושמירת התוצאות בגרף

בדוגמה הזו נעשה שימוש בתבנית MATCH כדי להתאים באופן דינמי תת-גרף לוגי שמכיל את כל הצמתים Account ורק קשתות Transfer עם סכום שקטן מ-500. תת-התרשים הלוגי הזה הוא הקלט של האלגוריתם PageRank. ‫Spanner שומר את תוצאות האלגוריתם בחזרה בטבלה Account.

EXPORT DATA OPTIONS (
  format = "CLOUD_SPANNER",
  table = "Account",
  write_mode = 'update_ignore_all'
) AS
GRAPH FinGraph
MATCH (n:Account)
RETURN n
FULL UNION ALL
MATCH -[e:Transfers WHERE e.amount < 500]->
RETURN e
NEXT
CALL PER () PageRank() YIELD node, score
RETURN node.id, score AS page_rank

אחרי שהשאילתה מסתיימת, מריצים את השאילתה הבאה:

GRAPH FinGraph
MATCH (n:Account)
RETURN n.id, ROUND(n.page_rank, 2) AS page_rank
ORDER BY page_rank DESC, id ASC

אמורות להתקבל תוצאות דומות לאלה:

id	page_rank
20	0.49
16	0.46
7	0.05

בדיקת סטטוס ההפעלה של האלגוריתם

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

`GRAPH_OPERATION_EXECUTION_STATUS` schema

שם עמודה	סוג	תיאור
`QUERY_ID`	`STRING`	המזהה של שאילתת אלגוריתם הגרף.
`QUERY_TEXT`	`STRING`	טקסט הצהרת השאילתה.
`START_TIMESTAMP`	`TIMESTAMP`	השעה שבה התחילה הרצת השאילתה.
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	המועד שבו הסטטוס עודכן לאחרונה.
`PROGRESS`	`FLOAT64`	אחוז ההשלמה המשוער. הערך הוא בין `0` ל-`1`, כאשר `0` מייצג התחלה ו-`1` מייצג סיום.
`STATUS`	`STRING`	המצב הנוכחי של ההרצה. הערכים האפשריים כוללים את `PENDING`,‏ `IN_PROGRESS`,‏ `OK` או קוד סטטוס של שגיאה כמו `CANCELLED`,‏ `DEADLINE_EXCEEDED`,‏ `INVALID_ARGUMENT`,‏ `FAILED_PRECONDITION`,‏ `RESOURCE_EXHAUSTED`,‏ `UNAVAILABLE` או `UNKNOWN`.
`ERROR_MESSAGE`	`STRING`	הודעת שגיאה אם הרצת השאילתה נכשלה.

השאילתה לדוגמה הבאה מפרטת שאילתות גרף שעדיין לא הושלמו בהצלחה:

SELECT
  query_id,
  query_text,
  start_timestamp,
  last_update_timestamp,
  progress,
  status,
  error_message
FROM
  SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS
WHERE
  status != "OK"
ORDER BY
  start_timestamp DESC;

ביטול הרצת האלגוריתם

כדי לבטל שאילתה של אלגוריתם גרף שפועלת, מאתרים את ה-query_id מהטבלה SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS ואז קוראים ל-cancel_query בשביל ה-query_id הזה.