מטרות
במדריך הזה נסביר איך לבצע את הפעולות הבאות באמצעות ספריית הלקוח של Spanner ל-C++:
- יוצרים מכונה ומסד נתונים ב-Spanner.
- לכתוב, לקרוא ולהריץ שאילתות SQL על נתונים במסד הנתונים.
- מעדכנים את הסכימה של מסד הנתונים.
- עדכון נתונים באמצעות טרנזקציית קריאה-כתיבה.
- מוסיפים אינדקס משני למסד הנתונים.
- משתמשים באינדקס כדי לקרוא ולהריץ שאילתות SQL על נתונים.
- אחזור נתונים באמצעות טרנזקציה לקריאה בלבד.
עלויות
במדריך הזה משתמשים ב-Spanner, רכיב שלGoogle Cloudשהשימוש בו כרוך בתשלום. למידע על עלות השימוש ב-Spanner, ראו תמחור.
לפני שמתחילים
מבצעים את השלבים שמפורטים בקטע הגדרה, שכוללים יצירה והגדרה של פרויקט Google Cloud כברירת מחדל, הפעלת החיוב, הפעלת Cloud Spanner API והגדרת OAuth 2.0 כדי לקבל פרטי כניסה לאימות לשימוש ב-Cloud Spanner API.
חשוב במיוחד להריץ את הפקודה gcloud auth
application-default login כדי להגדיר את סביבת הפיתוח המקומית עם פרטי הכניסה לאימות.
הכנת סביבת C++ מקומית
משכפלים את המאגר של האפליקציה לדוגמה ומעבירים אותו למכונה המקומית:
git clone https://github.com/googleapis/google-cloud-cpp $HOME/google-cloud-cppמתקינים את Bazel ל-Linux לפי ההוראות האלה.
עוברים לספרייה שמכילה את הקוד לדוגמה של Spanner:
cd $HOME/google-cloud-cppמריצים את הפקודה הבאה כדי ליצור את הדוגמאות:
bazel build //google/cloud/spanner/samples:samplesמגדירים אימות והרשאה לפרויקט
google-cloud-cpp.gcloud auth application-default loginיוצרים משתנה סביבה בשם
PROJECT_ID. מחליפים את [MY_PROJECT_ID] במזהה הפרויקט ב- Google Cloud . אפשר למצוא את המזהה הזה בדף Welcome של הפרויקט.export PROJECT_ID=[MY_PROJECT_ID]
יצירת מכונה
בפעם הראשונה שמשתמשים ב-Spanner, צריך ליצור מכונה – הקצאה של משאבים שמשמשים את מסדי הנתונים של Spanner. כשיוצרים מכונה, בוחרים הגדרת מכונה שקובעת איפה הנתונים יאוחסנו, וגם את מספר הצמתים שבהם משתמשים, שקובע את כמות משאבי האחסון וההצגה במכונה.
במאמר יצירת מכונה מוסבר איך ליצור מכונה של Spanner באמצעות אחת מהשיטות הבאות. אפשר לתת למכונה את השם test-instance כדי להשתמש בה עם נושאים אחרים במסמך הזה, שמתייחסים למכונה בשם test-instance.
- Google Cloud CLI
- מסוף Google Cloud
- ספריית לקוח (C++, C#, Go, Java, Node.js, PHP, Python, Ruby או Rust)
עיון בקבצים לדוגמה
מאגר הדוגמאות מכיל דוגמה שמראה איך להשתמש ב-Spanner עם C++.
עיינו בקובץ google/cloud/spanner/samples/samples.cc, שבו מוסבר איך ליצור מסד נתונים ולשנות סכימה של מסד נתונים. הנתונים משתמשים בסכימה לדוגמה שמוצגת בדף סכימה ומודל נתונים.
יצירת מסד נתונים
GoogleSQL
bazel run //google/cloud/spanner/samples:samples -- \
create-database PROJECT_ID test-instance example-db
PostgreSQL
bazel run //google/cloud/spanner/samples:postgresql_samples -- \
create-database PROJECT_ID test-instance example-db
bazel run //google/cloud/spanner/samples:postgresql_samples -- \
interleaved-table PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Created database [projects/${PROJECT_ID}/instances/test-instance/databases/example-db]
GoogleSQL
PostgreSQL
בניב PostgreSQL, צריך ליצור את מסד הנתונים לפני ששולחים בקשת DDL ליצירת טבלה.
בדוגמה הבאה נוצר מסד נתונים:
בדוגמה הבאה נוצרות שתי הטבלאות במסד הנתונים:
השלב הבא הוא כתיבת נתונים במסד הנתונים.
יצירת לקוח של מסד נתונים
כדי לבצע פעולות קריאה או כתיבה, צריך ליצור Client:
Client מאפשר לקרוא, לכתוב, לשלוח שאילתות ולבצע טרנזקציות במסד נתונים של Spanner. בדרך כלל יוצרים Client כשהאפליקציה מופעלת, ואז משתמשים שוב באותו Client כדי לקרוא, לכתוב ולבצע טרנזקציות. כל לקוח משתמש במשאבים ב-Spanner. ה-destructor של Client מנקה באופן אוטומטי את המשאבים של Client, כולל חיבורים לרשת.
מידע נוסף על Client זמין בGoogle Cloud מאמרי העזרה של Spanner C++.
כתיבת נתונים באמצעות DML
אפשר להוסיף נתונים באמצעות שפת טיפול בנתונים (DML) בטרנזקציית קריאה-כתיבה.
משתמשים בפונקציה Client::ExecuteDml() כדי להריץ פקודת DML.
מריצים את הדוגמה באמצעות הארגומנט getting-started-insert.
bazel run //google/cloud/spanner/samples:samples -- \
getting-started-insert PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Insert was successful [spanner_dml_getting_started_insert]
כתיבת נתונים באמצעות מוטציות
אפשר גם להוסיף נתונים באמצעות מוטציות.
כדי לכתוב נתונים, משתמשים באובייקט Client. הפונקציה Client::Commit() יוצרת טרנזקציה ומאשרת אותה לפעולות כתיבה שמתבצעות באופן אטומי בנקודת זמן לוגית אחת בעמודות, בשורות ובטבלאות במסד נתונים.
הקוד הזה מראה איך לכתוב את הנתונים באמצעות מוטציות:
מריצים את הדוגמה באמצעות הארגומנט insert-data.
bazel run //google/cloud/spanner/samples:samples -- \
insert-data PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Insert was successful [spanner_insert_data]
הרצת שאילתות על נתונים באמצעות SQL
ב-Spanner יש תמיכה בממשק SQL לקריאת נתונים, שאפשר לגשת אליו בשורת הפקודה באמצעות Google Cloud CLI או באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C++.
בשורת הפקודה
מריצים את הצהרת ה-SQL הבאה כדי לקרוא את הערכים של כל העמודות מהטבלה Albums:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
תחביר Pipe ב-GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='FROM Albums |> SELECT SingerId, AlbumId, AlbumTitle'
בתוצאה רואים:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
שימוש בספריית הלקוח של Spanner ל-C++
בנוסף להרצת הצהרת SQL בשורת הפקודה, אפשר להנפיק את אותה הצהרת SQL באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C++.
כדי להריץ את שאילתת ה-SQL, משתמשים בפונקציה Client::ExecuteQuery().
כך מריצים את השאילתה וניגשים לנתונים:
מריצים את הדוגמה באמצעות הארגומנט query_data.
bazel run //google/cloud/spanner/samples:samples -- \
query-data PROJECT_ID test-instance example-db
התוצאה הבאה אמורה להופיע:
SingerId: 1 LastName: Richards
SingerId: 2 LastName: Smith
SingerId: 3 LastName: Trentor
SingerId: 4 LastName: Martin
SingerId: 5 LastName: Lomond
SingerId: 12 LastName: Garcia
SingerId: 13 LastName: Morales
SingerId: 14 LastName: Long
SingerId: 15 LastName: Shaw
שאילתה באמצעות פרמטר SQL
אם באפליקציה שלכם יש שאילתה שמופעלת לעיתים קרובות, אתם יכולים לשפר את הביצועים שלה על ידי הוספת פרמטרים. אפשר לשמור במטמון את השאילתה הפרמטרית שנוצרה ולהשתמש בה שוב, וכך להפחית את עלויות ההידור. למידע נוסף, קראו את המאמר שימוש בפרמטרים של שאילתות כדי להאיץ שאילתות שמבוצעות לעיתים קרובות.
הנה דוגמה לשימוש בפרמטר בסעיף WHERE כדי לשלוח שאילתה על רשומות שמכילות ערך ספציפי של LastName.
GoogleSQL
PostgreSQL
מריצים את הדוגמה באמצעות הפקודה query-with-parameter.
bazel run //google/cloud/spanner/samples:samples -- \
query-with-parameter PROJECT_ID test-instance example-db
התוצאה הבאה אמורה להופיע:
SingerId: 12 FirstName: Melissa LastName: Garcia
קריאת נתונים באמצעות Read API
בנוסף לממשק ה-SQL של Spanner, יש גם ממשק קריאה.
כדי לקרוא שורות ממסד הנתונים, משתמשים בפונקציה Client::Read(). משתמשים באובייקט KeySet כדי להגדיר אוסף של מפתחות וטווחי מפתחות לקריאה.
כך קוראים את הנתונים:
מריצים את הדוגמה באמצעות הארגומנט read-data.
bazel run //google/cloud/spanner/samples:samples -- \
read-data PROJECT_ID test-instance example-db
הפלט אמור להיראות כך:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
עדכון הסכימה של מסד הנתונים
נניח שאתם צריכים להוסיף עמודה חדשה בשם MarketingBudget לטבלה Albums. כדי להוסיף עמודה חדשה לטבלה קיימת, צריך לעדכן את הסכימה של מסד הנתונים. ב-Spanner אפשר לעדכן את הסכימה של מסד הנתונים בזמן שמסד הנתונים ממשיך לשרת את התנועה. עדכוני סכימה לא דורשים להעביר את מסד הנתונים למצב אופליין, והם לא נועלים טבלאות או עמודות שלמות. אפשר להמשיך לכתוב נתונים במסד הנתונים במהלך עדכון הסכימה. במאמר עדכוני סכימה מוסבר איך לעדכן סכימות ואיך השינויים בסכימה משפיעים על הביצועים.
הוספת עמודה
אפשר להוסיף עמודה בשורת הפקודה באמצעות Google Cloud CLI או באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C++.
בשורת הפקודה
משתמשים בפקודה הבאה של ALTER TABLE כדי להוסיף את העמודה החדשה לטבלה:
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
אמורה להופיע ההודעה:
Schema updating...done.
שימוש בספריית הלקוח של Spanner ל-C++
משתמשים בפונקציה DatabaseAdminClient::UpdateDatabase() כדי לשנות את הסכימה.
GoogleSQL
PostgreSQL
מריצים את הדוגמה באמצעות הפקודה add-column.
bazel run //google/cloud/spanner/samples:samples -- \
add-column PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Added MarketingBudget column
כתיבת נתונים בעמודה החדשה
הקוד הבא כותב נתונים בעמודה החדשה. היא מגדירה את MarketingBudget לערך 100000 בשורה עם מפתח השורה Albums(1, 1), ולערך 500000 בשורה עם מפתח השורה Albums(2, 2).
מריצים את הדוגמה באמצעות הארגומנט update-data.
bazel run //google/cloud/spanner/samples:samples -- \
update-data PROJECT_ID test-instance example-db
אפשר גם להריץ שאילתת SQL או קריאת קריאה כדי לאחזר את הערכים שכתבתם.
זה הקוד להרצת השאילתה:
כדי להריץ את השאילתה הזו, מריצים את הדוגמה באמצעות הארגומנט query-new-column.
bazel run //google/cloud/spanner/samples:samples -- \
query-new-column PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
SingerId: 1 AlbumId: 1 MarketingBudget: 100000
SingerId: 1 AlbumId: 2 MarketingBudget: NULL
SingerId: 2 AlbumId: 1 MarketingBudget: NULL
SingerId: 2 AlbumId: 2 MarketingBudget: 500000
SingerId: 2 AlbumId: 3 MarketingBudget: NULL
עדכון נתונים
אפשר לעדכן נתונים באמצעות DML בעסקה של קריאה וכתיבה.
משתמשים בפונקציה Client::ExecuteDml() כדי להריץ פקודת DML.
GoogleSQL
PostgreSQL
מריצים את הדוגמה באמצעות הארגומנט getting-started-update.
bazel run //google/cloud/spanner/samples:samples -- \
getting-started-update PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Update was successful [spanner_dml_getting_started_update]
שימוש באינדקס משני
נניח שאתם רוצים לאחזר את כל השורות של Albums שיש בהן ערכי AlbumTitle בטווח מסוים. אפשר לקרוא את כל הערכים מהעמודה AlbumTitle באמצעות הצהרת SQL או קריאה, ואז למחוק את השורות שלא עומדות בקריטריונים. עם זאת, סריקה של כל הטבלה היא פעולה יקרה, במיוחד בטבלאות עם הרבה שורות. במקום זאת, כדי לאחזר שורות מהר יותר כשמחפשים לפי עמודות שהן לא מפתח ראשי, אפשר ליצור אינדקס משני בטבלה.
כדי להוסיף אינדקס משני לטבלה קיימת, צריך לעדכן את הסכימה. כמו עדכוני סכימה אחרים, Spanner תומך בהוספת אינדקס בזמן שמסד הנתונים ממשיך לשרת את התנועה. Spanner ממלא באופן אוטומטי את החוסרים באינדקס באמצעות הנתונים הקיימים. מילויים חוזרים עשויים להימשך כמה דקות, אבל לא צריך להעביר את מסד הנתונים למצב אופליין או להימנע מכתיבה בטבלה שנוסף לה אינדקס במהלך התהליך הזה. למידע נוסף, קראו את המאמר הוספת אינדקס משני.
אחרי שמוסיפים אינדקס משני, Spanner משתמש בו באופן אוטומטי לשאילתות SQL שסביר להניח שיפעלו מהר יותר עם האינדקס. אם אתם משתמשים בממשק הקריאה, אתם צריכים לציין את האינדקס שבו אתם רוצים להשתמש.
הוספת אינדקס משני
אפשר להוסיף אינדקס בשורת הפקודה באמצעות ה-CLI של gcloud, או באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C++.
בשורת הפקודה
משתמשים בפקודה הבאה של CREATE INDEX כדי להוסיף אינדקס למסד הנתונים:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
אמורה להופיע ההודעה:
Schema updating...done.
שימוש בספריית הלקוח של Spanner ל-C++
משתמשים בפונקציה DatabaseAdminClient::UpdateDatabase() כדי להוסיף אינדקס:
מריצים את הדוגמה באמצעות הארגומנט add-index.
bazel run //google/cloud/spanner/samples:samples -- \
add-index PROJECT_ID test-instance example-db
הוספת אינדקס יכולה להימשך כמה דקות. אחרי שהאינדקס נוסף, אמור להופיע פלט דומה לזה:
`AlbumsByAlbumTitle` Index successfully added, new DDL:
database: "projects/PROJECT_ID/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
commit_timestamps {
seconds: 1581011550
nanos: 531102000
}
קריאה באמצעות האינדקס
בשאילתות SQL, Spanner משתמש באופן אוטומטי באינדקס מתאים. בממשק הקריאה, צריך לציין את האינדקס בבקשה.
כדי להשתמש באינדקס בממשק הקריאה, משתמשים בפונקציה Client::Read(), שקוראת אפס שורות או יותר ממסד נתונים באמצעות אינדקס.
הקוד הבא מאחזר את כל העמודות של AlbumId ו-AlbumTitle מהאינדקס AlbumsByAlbumTitle.
מריצים את הדוגמה באמצעות הארגומנט read-data-with-index.
bazel run //google/cloud/spanner/samples:samples -- \
read-data-with-index PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
AlbumId: 2 AlbumTitle: Forever Hold Your Peace
AlbumId: 2 AlbumTitle: Go, Go, Go
AlbumId: 1 AlbumTitle: Green
AlbumId: 3 AlbumTitle: Terrified
AlbumId: 1 AlbumTitle: Total Junk
הוספת אינדקס לקריאות של אינדקס בלבד
אולי שמתם לב שהדוגמה הקודמת של קריאה לא כוללת קריאה של העמודה MarketingBudget. הסיבה לכך היא שממשק הקריאה של Spanner לא תומך באפשרות לצרף אינדקס לטבלת נתונים כדי לבצע חיפוש מהיר של ערכים שלא מאוחסנים באינדקס.
יוצרים הגדרה חלופית של AlbumsByAlbumTitle ששומרת עותק של MarketingBudget באינדקס.
בשורת הפקודה
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
הוספת אינדקס יכולה להימשך כמה דקות. אחרי שמוסיפים את האינדקס, אמור להופיע:
Schema updating...done.
שימוש בספריית הלקוח של Spanner ל-C++
משתמשים בפונקציה DatabaseAdminClient::UpdateDatabase() כדי להוסיף אינדקס עם משפט STORING עבור :
מריצים את הדוגמה באמצעות הארגומנט add-storing-index.
bazel run //google/cloud/spanner/samples:samples -- \
add-storing-index PROJECT_ID test-instance example-db
הפלט אמור להיראות כך:
`AlbumsByAlbumTitle2` Index successfully added, new DDL:
database: "projects/PROJECT_ID/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)"
commit_timestamps {
seconds: 1581012328
nanos: 416682000
}
עכשיו אפשר לבצע קריאה שמאחזרת את כל העמודות AlbumId, AlbumTitle ו-MarketingBudget מהאינדקס AlbumsByAlbumTitle2:
כדי לקרוא נתונים באמצעות אינדקס האחסון שיצרתם, מריצים שאילתה שמציינת במפורש את האינדקס:
מריצים את הדוגמה באמצעות הארגומנט read-data-with-storing-index.
bazel run //google/cloud/spanner/samples:samples -- \
read-data-with-storing-index PROJECT_ID test-instance example-db
הפלט אמור להיראות כך:
AlbumId: 2 AlbumTitle: Forever Hold Your Peace MarketingBudget: 520000
AlbumId: 2 AlbumTitle: Go, Go, Go MarketingBudget: NULL
AlbumId: 1 AlbumTitle: Green MarketingBudget: NULL
AlbumId: 3 AlbumTitle: Terrified MarketingBudget: NULL
AlbumId: 1 AlbumTitle: Total Junk MarketingBudget: 80000
אחזור נתונים באמצעות עסקאות לקריאה בלבד
נניח שאתם רוצים לבצע יותר מקריאה אחת באותה חותמת זמן. עסקאות לקריאה בלבד צופות בתחילית עקבית של היסטוריית ה-commit של העסקה, כך שהאפליקציה תמיד מקבלת נתונים עקביים.
הסוג Transaction משמש לייצוג כל סוגי העסקאות.
משתמשים בפונקציית ה-factory MakeReadOnlyTransaction() כדי ליצור טרנזקציה לקריאה בלבד.
כך מריצים שאילתה ומבצעים קריאה באותה עסקה לקריאה בלבד:
מריצים את הדוגמה באמצעות הארגומנט read-only-transaction.
bazel run //google/cloud/spanner/samples:samples -- \
read-only-transaction PROJECT_ID test-instance example-db
הפלט אמור להיראות כך:
Read 1 results
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold Your Peace
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified
SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
Read 2 results
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold Your Peace
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified
SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
הסרת המשאבים
כדי להימנע מחיובים נוספים בחשבון לחיוב ב-Cloud על המשאבים שבהם השתמשתם במדריך הזה, אתם צריכים למחוק את מסד הנתונים ואת המכונה שיצרתם.
מחיקת מסד הנתונים
אם מוחקים מכונה, כל מסדי הנתונים שבתוכה נמחקים באופן אוטומטי. בשלב הזה מוסבר איך למחוק מסד נתונים בלי למחוק מכונה (עדיין תחויבו על המכונה).
בשורת הפקודה
gcloud spanner databases delete example-db --instance=test-instance
באמצעות מסוף Google Cloud
נכנסים לדף Spanner Instances במסוף Google Cloud .
לוחצים על המופע.
לוחצים על מסד הנתונים שרוצים למחוק.
בדף Database details, לוחצים על Delete.
מאשרים שרוצים למחוק את מסד הנתונים ולוחצים על מחיקה.
מחיקת המכונה
מחיקת מכונה גורמת להסרה אוטומטית של כל מסדי הנתונים שנוצרו בה.
בשורת הפקודה
gcloud spanner instances delete test-instance
באמצעות מסוף Google Cloud
נכנסים לדף Spanner Instances במסוף Google Cloud .
לוחצים על המכונה.
לוחצים על Delete.
מאשרים שרוצים למחוק את המכונה ולוחצים על Delete.
המאמרים הבאים
במאמר אימות לשירותי Cloud באמצעות ספריות לקוח תוכלו לקרוא מידע נוסף על פרטי כניסה לאימות ולהרשאה.