פורמט הפלט מ-CLI של cbt

במאמר הזה מוסבר איך לעצב סוגים ספציפיים של נתונים שמאוחסנים בשורות Bigtable כשמציגים אותם באמצעות cbt CLI.

דוגמאות לעיצוב

החל מגרסה 0.12.0, ממשק שורת הפקודה (CLI) של cbt יכול לעצב סוגים מורכבים מסוימים של נתונים שמאוחסנים בשורות בטבלה. כשמשתמשים בפקודה cbt read או בפקודה cbt lookup, אפשר להשתמש ב-CLI של cbt כדי להציג את הערכים שמאוחסנים בשורות בפורמט קריא.

בדוגמה הבאה מוצג פלט נתונים מ-CLI‏ cbt ללא עיצוב.

----------------------------------------
r1
  fam1:col1                                 @ 2022/03/09-11:19:45.966000
    "\n\x05Brave\x10\x02"
  fam1:col2                                 @ 2022/03/14-11:17:20.014000
    "{\"name\": \"Brave\", \"age\": 2}"

בדוגמה הבאה מוצג פלט נתונים מ-CLI‏ cbt עם עיצוב.

r1
  fam1:col1                                 @ 2022/03/09-11:19:45.966000
    name: "Brave"
    age: 2
  fam1:col2                                 @ 2022/03/14-11:17:20.014000
    age:     2.00
    name:   "Brave"

הדפסת שורות עם עיצוב

כדי לעצב עמודה או קבוצת עמודות, צריך לספק קובץ YAML שבו מצוין העיצוב של העמודה. כשמתקשרים אל cbt lookup או אל cbt read, מעבירים את הנתיב לקובץ ה-YAML עם הארגומנט format-file. בקטע הקוד הבא מוצגת דוגמה להפעלה של cbt lookup עם הארגומנט format-file.

cbt lookup my-table r1 format-file=/path/to/formatting.yml

הגדרת פורמטים של נתוני עמודות ב-YAML

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

protocol_buffer_definitions:
  - cat.proto
protocol_buffer_paths:
  - testdata/


columns:
  col1:
    encoding: ProtocolBuffer
    type: Cat

  col2:
    encoding: json

בקטע הקוד הבא מוצג התוכן של cat.proto.

syntax = "proto3";
package cats;

option go_package = "github.com/protocolbuffers/protobuf/examples/go/tutorialpb";

message Cat {
  string name = 1;
  int32 age = 2;
}

בדוגמה הזו:

• השדה protocol_buffer_definitions מספק רשימה של קובצי ‎ .proto שיכולים להכיל סוגים של הודעות מאגר אחסון לפרוטוקולים שאפשר להשתמש בהם כדי לפענח נתוני protobuf.
• השדה protocol_buffer_paths מספק רשימה של נתיבים מקומיים שיכולים להכיל קובצי ‎ .proto לפענוח סוגים של מאגר אחסון לפרוטוקולים. אין צורך לציין את המיקומים של יבוא של מאגרי אחסון לפרוטוקולים סטנדרטיים, כמו הודעות בחבילה google/protobuf.

• השדה columns מכיל רשימה של שמות עמודות עם סוגי הנתונים המתאימים לכל עמודה:

  • העמודה protobuf מוגדרת כ-ProtocolBuffer, והעמודה type מוגדרת כ-Cat.encoding ממשק שורת הפקודה cbt מפרש ומעצב את כל הערכים שמאוחסנים בעמודה הזו כסוג הודעת פרוטו Cat. הסוג חייב להיות תואם לסוג הודעה שמוגדר באחד מקובצי ה-proto שסופקו לשדה protocol_buffer_definition.
  • השדה encoding בעמודה json מוגדר כ-'json'. הפונקציה cbt מפרשת ומעצבת את כל הערכים שמאוחסנים בעמודה הזו כמבנה JSON.

שדות אחרים שאפשר למלא:

• ‫default_encoding: השדה הזה מגדיר פורמט ברירת מחדל לכל העמודות בטבלה או לכל העמודות במשפחת עמודות.
• ‫default_type: השדה הזה מגדיר סוג נתונים שמוגדר כברירת מחדל לעמודות מקודדות של מאגר אחסון לפרוטוקולים, Big-endian ו-Little-endian.

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

  families:
    family1:
      default_encoding: BigEndian
      default_type: INT64
      columns:
        address:
          encoding: PROTO
          type: tutorial.Person
  

סוגי נתונים נתמכים

‫cbt CLI תומך בעיצוב של כמה סוגים מורכבים של נתונים. בטבלה הבאה מפורטים סוגי הנתונים והמחרוזות הנתמכים שצריך לציין בקובץ ה-YAML לכל אחד מסוגי הרשימות. ערכי מחרוזת לא תלויי רישיות.

סוג נתונים	ערך הפורמט ב-YAML
הקסדצימלי	Hex, H
Big-endian	BigEndian, B
Little-endian	LittleEndian, L
מאגר אחסון לפרוטוקולים	ProtocolBuffer, P, PROTO
JSON	JSON, J

טבלה 1. סוגי הנתונים שנתמכים לעיצוב בפלט של cbt.

• הקידוד ההקסדצימלי לא תלוי בסוג. הנתונים מוצגים כייצוג הקסדצימלי הגולמי של הנתונים המאוחסנים.
• הסוגים הזמינים לקידודים big-endian ו-little-endian הם int8,‏ int16,‏ int32,‏ int64,‏ uint8,‏ uint16,‏ uint32,‏ uint64,‏ float32 ו-float64. אורך הנתונים המאוחסנים חייב להיות כפולה של גודל הסוג, בבייטים. הנתונים מוצגים כערכים סקלריים אם האורך המאוחסן תואם לגודל הסוג, או כמערכים אחרת. בשמות של סוגים אין הבחנה בין אותיות רישיות לקטנות.
• הסוגים שצוינו לקידוד protocol-buffer צריכים להיות זהים לסוגי ההודעות שמוגדרים בקובצי ההגדרה של פרוטוקול מאגר הנתונים הזמני שסופקו. הסוגים לא תלויי רישיות (case-sensitive). אם לא מציינים סוג, ברירת המחדל היא שם העמודה של נתוני העמודה שמוצגים.
• הערכים של הפורמט ב-YAML לא תלויי-רישיות.