כלי לאימות סגנון של אינטגרציה רציפה

כדי לאכוף את תקני הקידוד של LookML, מוסכמות השמות והשיטות המומלצות המבניות בפרויקט של LookML, כלי האימות של סגנון האינטגרציה הרציפה (CI) משתמש ב-LookML Style Linter. כלי אימות הסגנון בודק את קובצי LookML בהשוואה לקבוצה של כללי סגנון שניתנים להגדרה, וכך עוזר לצוות שלכם לשמור על בסיס קוד נקי, עקבי וקריא.

כדי להריץ את הכלי Style Validator, צריך להוסיף קובץ תצורה בשם lkmlstyle.yaml (או lkmlstyle.yml) לתיקיית השורש של מאגר פרויקט של LookML. פרטים על הגדרת הכלי לבדיקת סגנון מופיעים בקטע קובץ ההגדרות בדף הזה.

מידע על הגדרה והפעלה של הכלי Style Validator בחבילת CI ועל צפייה בפלט של האימות זמין בדפי התיעוד בנושא יצירת חבילת Continuous Integration, הפעלה של חבילות Continuous Integration וצפייה בתוצאות של הפעלת CI.

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

כדי להשתמש בכלי לאימות סגנון באינטגרציה רציפה (CI), אתם צריכים:

קובץ תצורה

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

  1. lkmlstyle.yaml
  2. lkmlstyle.yml

אם שני הקבצים קיימים בתיקיית השורש, הקובץ lkmlstyle.yaml מקבל עדיפות והמערכת מתעלמת מהקובץ lkmlstyle.yml.

אם אף אחד מהקבצים lkmlstyle.yaml או lkmlstyle.yml לא נמצא בתיקיית השורש של הפרויקט (ולא מועברת הגדרה מותאמת אישית דרך ה-API), אימות הסגנון נכשל עם השגיאה "No style validator configuration provided".

כדי להריץ את כל 25 הכללים המובנים עם הגדרות ברירת המחדל שלהם, אפשר להשתמש בפרטי ההגדרה המינימליים הבאים בקובץ lkmlstyle.yaml:

schema_version: 1
ruleset_version: "all-v1.0"

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

פרמטר סוג חובה? ברירת מחדל תיאור
schema_version מספר שלם כן ללא גרסת סכימת ההגדרה. גרסה 1 היא הגרסה היחידה שנתמכת, וחובה לציין אותה באופן מפורש.
ruleset_version String כן ללא מהדורת חבילת הכללים של תצורת הבסיס שממנה יתבצעת הירושה. ערכים נתמכים: "all-v1.0", ‏ "none".
ignore_files רשימת מחרוזות לא [] תבניות Glob של קבצים שצריך להחריג לחלוטין מאימות הסגנון.
rules מפה לא {} התאמות אישיות גלובליות (severity ו-version) לכללים ספציפיים. אפשר גם להפעיל כללים מובְנים שלא נכללים בקבוצת הכללים של תצורת הבסיס, ולשנות את דרגת החומרה של כללים מותאמים אישית. דוגמאות מופיעות בקטע התאמה אישית של כללים.
overrides רשימת מפות לא [] החלפת כללים בהיקף מוגבל שמשנים או מפעילים רמות חומרה עבור נתיבי קבצים ספציפיים שתואמים לכלל.
custom_rules רשימת מפות לא [] כללים מותאמים אישית דקלרטיביים שמוגדרים על ידי המשתמש.

ruleset_version

הפרמטר ruleset_version מגדיר את הבסיס של אסטרטגיית האימות של הסגנון:

  • ‫"all-v1.0" (מומלץ): מפעיל את כל 25 הכללים המובנים הרגילים של סגנון LookML ברמת החומרה error. האפשרות הזו מתאימה במיוחד לצוותים שרוצים לאכוף את איכות הקוד באופן מקיף, ללא צורך בהגדרות נוספות.
  • ‫"none": מתחיל עם אפס כללים מובנים שמופעלים. האפשרות הזו מתאימה לצוותים שרוצים להטמיע את אימות הסגנון בהדרגה, להפעיל כללים ספציפיים בנפרד או להפעיל רק כללים ארגוניים מותאמים אישית. כדי להפעיל כלל מובנה כש-ruleset_version הוא "none", צריך להקצות לכלל חומרה ברמה warn או error בבלוק rules או בבלוק overrides.

ignore_files

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

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

  • ‫*: התאמה לכל רצף של תווים שאינם מפרידים ברמה של ספרייה אחת.
  • ‫**: התאמה לכל רצף של תווים בכמה רמות של ספריות במבנה היררכי.
  • ‫?: התאמה לכל תו יחיד.
  • ‫{a,b} ו-[abc]: התאמה לחלופות ולמחלקות של תווים (תחביר glob של Java).

כללי ההתאמה הבאים לנתיבים חלים על כל תבנית glob בקובץ התצורה, כולל ignore_files ברמה העליונה וגם files ו-ignore_files ב-overrides:

  • הנתיבים הם יחסיים לתיקיית השורש של הפרויקט. המערכת מתעלמת מ-./ או מ-/ בתחילת הטקסט.
  • תבנית ללא לוכסן (/) מתאימה לכל עומק של ספרייה. לדוגמה, *.ignore.lkml תואם ל-x.ignore.lkml ול-views/x.ignore.lkml.
  • תבנית שמסתיימת ב-/ מתאימה לכל מה שנמצא בספרייה הזו.
  • תבנית שמסתיימת ב-.lkml או ב-.lookml תואמת גם לסיומות מורכבות. לדוגמה, *.ignore.lkml תואם ל-x.ignore.view.lkml.

בדוגמה הבאה לא נכללים קבצים של ספקים, קובצי LookML מדור קודם ומרכזי שליטה של LookML:

ignore_files:
  - "vendor/**"
  - "legacy/**/*.lkml"
  - "*.ignore.lkml"
  - "dashboards/*.dashboard.lookml"

rules

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

rules:
  boolean-dimension-name-prefix:
    severity: warn
  view-dimension-order:
    severity: disabled
  numeric-measure-value-format-presence:
    severity: error

כל כלל מובנה שמופיע ב-rules (או בבלוק overrides) עם חומרה ברמה warn או error פעיל, גם אם ruleset_version מוגדר ל-"none". לדוגמה, הגדרת ההתחלה הבאה מתחילה עם ruleset_version: "none" ומפעילה רק שני כללים מובנים:

schema_version: 1
ruleset_version: "none"

rules:
  join-relationship-presence:
    severity: error
  explore-label-presence:
    severity: warn

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

severity

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

  • ‫error: נחשב להפרה חמורה. שגיאות גורמות לכך שהרצת ה-CI תיכשל.
  • ‫warn: מופיע כאזהרה שלא חוסמת את הפעולה. אזהרות מופיעות בדוחות של הרצת CI, אבל הן לא גורמות להרצת ה-CI להיכשל.
  • ‫disabled: משבית את הכלל לחלוטין ומדלג עליו במהלך האימות.

overrides

אתם יכולים להשתמש בפרמטר overrides כדי לשנות את רמות החומרה של הכללים בקבצים או בספריות ספציפיים, בלי לשנות את רמות החומרה בשאר הפרויקט של LookML. לדוגמה, אפשר להשתמש ב-overrides כדי להקל על הכללים בתצוגות של סביבות פיתוח או במודלים מדור קודם, להחמיר את הכללים בנתיבים קריטיים או להפעיל כללים ספציפיים רק בספריות מסוימות כש-ruleset_version הוא "none".

כל רשומה ברשימה overrides תומכת בשדות הבאים:

שדה סוג חובה? תיאור
files רשימת מחרוזות כן תבניות Glob שתואמות לקבצים שהבלוק הזה של ביטול ההגדרה חל עליהם. צריך לתת שם לקבוצה.
ignore_files רשימת מחרוזות לא תבניות Glob להחרגה מקטע ההחלפה הספציפי הזה.
rules מפה כן מיפוי של שמות כללים להגדרות חומרה. צריך לתת שם לקבוצה. אפשר להשתמש רק ב-severity (והשימוש בו נדרש) בבלוקים של ביטול הגדרות. השמות של הכללים חייבים להיות שמות תקינים של כללים מובנים או מותאמים אישית.

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

overrides:
  - files:
      - "views/legacy/**"
      - "dashboards/*.dashboard.lookml"
    ignore_files:
      - "views/legacy/core_*.view.lkml"
    rules:
      view-dimension-order:
        severity: disabled
      visible-dimension-description-presence:
        severity: warn

custom_rules

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

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

שדה סוג חובה? תיאור
name String כן מזהה ייחודי, בפורמט dash-case לפי המוסכמה, כמו finance-measure-prefix. השם לא יכול להיות זהה לשמות של כללים מובנים או של כללים אחרים בהתאמה אישית.
title String כן הודעה קריאה לאנשים שדווחה כשמתרחשת הפרה, בפורמט (<rule-name>) <title>.
rule_type String כן ארכיטיפ הכלל: pattern_match,‏ property,‏ order,‏ first_child או unique. לא תלוי-רישיות; הערך pattern מתקבל ככינוי לערך pattern_match.
severity String לא רמת האבחון: error (ברירת מחדל), warn או disabled. אפשר לשנות את ההגדרה הזו באמצעות rules ו-overrides.
rationale String לא מסמכים שמסבירים למה הכלל קיים.
select מחרוזת או רשימה לא נתיב הצומת של עץ התחביר המופשט (AST) אל היעד, כמו "view.dimension", "explore" או ["dimension", "dimension_group"]. אם לא מציינים את הערך הזה, הכלל יחול על כל צומת שתואם ל-filters.
filters מפה לא מסנני מאפיינים שצריכים להתאים לצומת היעד, כמו primary_key: true.
parent_filters מפה לא מסנני מאפיינים שצריכים להתאים להורה המיידי של הצומת המטורגט.

כל סוג של כלל מקבל רק מפתחות ספציפיים לסוג שלו. מפתחות לא מוכרים או מפתחות ששייכים לסוג אחר של כלל (למשל, order_by בכלל pattern_match) מובילים לשגיאת הגדרה.

select

הפרמטר select קובע אילו רכיבי LookML הכלל המותאם אישית מעריך:

  • רכיב ישיר: טירגוט של סוג ספציפי של רכיב LookML, כמו select: "dimension",‏ select: "measure",‏ select: "view",‏ select: "explore",‏ select: "join",‏ select: "model" או select: "include".
  • נתיב הורה-צאצא מוטמע: טירגוט רכיבים שמוגדרים בתוך הורה מיידי ספציפי, כמו select: "view.dimension" (מאפיינים שמוגדרים בתוך תצוגות) או select: "explore.join" (צירופים שמוגדרים בתוך ניתוחים). ההורה חייב להיות ההורה המיידי, ומשתמשים רק בשני הפלחים האחרונים של נתיב (כך ש-a.b.c מתנהג כמו b.c).
  • כמה יעדים: אפשר לטרגט כמה סוגים של רכיבים באמצעות מחרוזת או רשימה שמופרדות בפסיקים, כמו select: "dimension, dimension_group" או select: ["dimension", "dimension_group"].

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

filters וגם parent_filters

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

type: "string"
  • שוויון בוליאני: התאמה של מאפיינים בוליאניים שהוגדרו במפורש, כמו primary_key: true או hidden: true.
  • שוויון מחרוזות: התאמה של ערכי מחרוזות מדויקים, כמו type: "yesno" או type: "count".
  • רשימה של ערכים אפשריים: התאמה לכל ערך ברשימה, כמו type: ["string", "number", "date"].
  • בדיקת נוכחות: כדי לבדוק אם בלוק או מאפיין קיימים, מעבירים מחרוזת ריקה, כמו derived_table: "".
  • שלילה: מוסיפים את הקידומת ! למפתח או לערך כדי לשלול את המסנן. מפתח עם שלילה צריך להיות בתוך מרכאות, כי אם לא, התו ! שמופיע בתחילת המפתח הוא תחביר של תג YAML, והניתוח של קובץ התצורה ייכשל:
    • "!hidden": true או hidden: "!true" תואם לפריטים גלויים (לא מוסתרים), כולל שדות שלא מוגדר בהם hidden.
    • ‫type: ["!yesno", "!date"] תואם לסוגים שהם לא yesno ולא date.

rule_type

בכל כלל מותאם אישית צריך לציין אחד מחמשת ארכיטיפים הכללים הבאים לפרמטר rule_type:

pattern_match

אכיפה של תבניות ביטויים רגולריים על שמות של ישויות LookML או על ערכי מאפיינים. צריך לציין אחד בלבד מהערכים match או should_not_match (אם מציינים את שניהם, רק match מוחל ומתעלמים מ-should_not_match):

  • ‫match (מחרוזת, ביטוי רגולרי): התבנית שהיעד צריך להתאים לה.
  • ‫should_not_match (מחרוזת, ביטוי רגולרי): תבנית שהיעד לא יכול להתאים לה.

הדפוסים הם ביטויים רגולריים של Java שעוברים אימות כשקובץ התצורה נטען. ההתאמה היא לא מעוגנת (התאמה של מחרוזת משנה). לדוגמה, match: "fin_" עובר עבור my_fin_total. כדי שתהיה התאמה לכל הערך, צריך להשתמש ב-^ וב-$.

אם select מכוון לנכס במקום לישות (לדוגמה, select: "measure.sql" או select: "dimension.label"), הביטוי הרגולרי מוערך לפי הערך של הנכס ולא לפי שם הישות. כך פועלים הכללים המובנים measure-sql-table-reference ו-dimension-label-redundant-yes-no.

דוגמה לאכיפה שלפיה מדדי מטבע מסתיימים ב-_usd או ב-_eur:

- name: currency-measure-suffix
  title: "Currency measures must end with a currency code like _usd or _eur"
  rule_type: pattern_match
  severity: error
  select: "view.measure"
  filters:
    value_format_name: ["usd", "usd_0", "eur", "eur_0"]
  match: "^.*_(usd|eur)$"

דוגמה לאיסור על מאפיינים זמניים או מאפיינים בטיוטה:

- name: forbid-temporary-dimensions
  title: "Dimensions must not start with 'tmp_' or 'test_'"
  rule_type: pattern_match
  severity: error
  select: "dimension"
  should_not_match: "^(tmp|test)_.*"
property

התכונה הזו אוכפת את הנוכחות או האיסור של מאפייני צאצא ספציפיים באובייקטים של LookML. צריך לציין אחד בלבד מהערכים requires_child או forbidden_child (אם מציינים את שניהם, רק requires_child מוחל ומתעלמים מ-forbidden_child):

  • ‫requires_child (מחרוזת או רשימה): שם או שמות של מאפיינים משניים שחייבים להיות נוכחים. כשמציינים רשימה, הכלל מתקיים אם אחד מהילדים שברשימה נמצא.
  • forbidden_child (מחרוזת או רשימה): שם או שמות של מאפיינים משניים שאסור שיופיעו. כשמציינים רשימה, הצומת מסומן אם אחד מפריטי הצאצא שמופיעים ברשימה נמצא.
  • ‫child_filters (מיפוי, אופציונלי): מסנני נכסים נוספים שהנכס המשני הנדרש צריך לעמוד בהם.

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

- name: require-visible-dimension-description
  title: "Visible dimensions must specify a description"
  rule_type: property
  severity: warn
  select: "view.dimension"
  filters:
    "!hidden": true
  requires_child: "description"

דוגמה לאיסור של sql_table_name בטבלאות נגזרות:

- name: forbid-sql-table-name-on-derived-views
  title: "Derived table views cannot specify sql_table_name"
  rule_type: property
  severity: error
  select: "view"
  filters:
    derived_table: ""
  forbidden_child: "sql_table_name"
order

הגדרת סדר אלפביתי לאלמנטים אחים בתוך מאגר.

  • ‫order_by (מחרוזת, חובה): סוג LookML של צאצאי האחים שצריך לסדר, בדרך כלל "dimension" או "measure". ההשוואה מתבצעת רק בין צאצאים ישירים של הצומת שנבחר, והצאצאים של dimension_group לא נכללים ב-"dimension".

השמות מושווים לפי קוד התו, תוך הבחנה בין אותיות רישיות לאותיות קטנות: אותיות רישיות ממוינות לפני אותיות קטנות, והתו _ ממוין ביניהן.

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

- name: custom-alphabetical-dimensions
  title: "Dimensions must be kept in alphabetical order within views"
  rule_type: order
  severity: error
  select: "view"
  order_by: "dimension"
first_child

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

  • ‫position (מחרוזת, אופציונלי): מגבלת מיקום. חייב להיות "first" (ברירת המחדל היא "first").

בכללי first_child, select צריך להשתמש בפורמט parent.child_type, כמו "view.dimension". הפרמטר filters מזהה את צומת הצאצא שצריך להופיע ראשון, אבל הוא לא מצמצם את מספר צמתי ההורה שנבדקים. הפרמטר parent_filters מתקבל על ידי הסכימה, אבל המערכת מתעלמת ממנו בסוג הכלל הזה.

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

- name: custom-primary-key-first-dimension
  title: "Primary key dimension must be the first dimension in the view"
  rule_type: first_child
  severity: error
  select: "view.dimension"
  filters:
    primary_key: true
  position: first
unique

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

  • ‫unique_property (מחרוזת, חובה): שם המאפיין שצריך לכלול ערכים ייחודיים בצמתים תואמים, כמו "sql_table_name" או "label".

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

דוגמה שמבטיחה שמות טבלאות ייחודיים בכל התצוגות:

- name: custom-sql-table-name-uniqueness
  title: "Each view must reference a unique sql_table_name"
  rule_type: unique
  severity: error
  select: "view"
  unique_property: "sql_table_name"

מגבלות של כללים מותאמים אישית

כשיוצרים כללים מותאמים אישית, צריך לפעול בהתאם למגבלות הבאות:

  1. אין התנגשות עם שמות של כללים מובנים: אי אפשר להשתמש בשם של כלל מובנה בקטלוג הכללים, כמו boolean-dimension-name-prefix או sql-table-name-uniqueness, כשיוצרים כלל בהתאמה אישית.
  2. שמות מותאמים אישית ייחודיים: לכל כלל מותאם אישית צריך להיות שם ייחודי ברשימה custom_rules.
  3. פורמט dash-case: בשמות של כללים צריך להשתמש בפורמט dash-case (lowercase-words-with-hyphens).

סדר ההערכה של ההגדרות

כשכלי האימות של הסגנון מעריך קובץ LookML, כללי ההגדרה מוחלים בסדר הבא:

  1. החרגת קובץ: אם הקובץ תואם לאחת מהתבניות ב-ignore_files, המערכת מדלגת על הקובץ לחלוטין.
  2. כללים פעילים: הכללים הפעילים לקובץ מורכבים מהכללים מ-ruleset_version (all-v1.0 או none), בתוספת כל כלל מובנה שהוקצתה לו חומרה ברמה warn או error ב-rules או בבלוק overrides תואם, בתוספת כל הכללים שמוגדרים ב-custom_rules.
  3. החלטה לגבי חומרת הבעיה: לכל כלל פעיל, ההגדרה הראשונה מבין ההגדרות הבאות שמציינת חומרה מקבלת עדיפות: בלוק overrides התואם האחרון, אחר כך בלוק rules הגלובלי, אחר כך severity של הכלל המותאם אישית ולבסוף חומרת ברירת המחדל (error).
  4. כללים מושבתים: המערכת מדלגת על כללים שהחומרה שלהם היא disabled.

קובץ הגדרה לדוגמה

בדוגמה הבאה מוצג קובץ lkmlstyle.yaml מלא שמדגים בחירה של קבוצת כללים בסיסית, החרגות של קבצים, התאמות אישיות של כללים גלובליים, ביטולים בהיקף מוגבל וכללים בהתאמה אישית:

# Schema version
schema_version: 1

# Baseline ruleset edition (all-v1.0 or none)
ruleset_version: "all-v1.0"

# Files completely ignored by the style validator
ignore_files:
  - "vendor/**"
  - "*.ignore.lkml"
  - "legacy_dashboards/*.dashboard.lookml"

# Built-in rule customizations
rules:
  view-dimension-order:
    severity: warn
  numeric-measure-value-format-presence:
    severity: warn
  sql-table-name-uniqueness:
    severity: error
  # Replaced by the custom first_child rule below
  primary-key-first-dimension:
    severity: disabled

# Directory/file scoped overrides
overrides:
  - files:
      - "views/staging/**"
    rules:
      visible-dimension-description-presence:
        severity: disabled
      primary-key-visibility:
        severity: warn

# Custom rules catalog
custom_rules:
  # 1. Pattern Match: Finance dimensions must start with fin_
  - name: finance-dimension-prefix
    title: "Finance dimensions must be prefixed with fin_"
    rule_type: pattern_match
    severity: error
    rationale: "Ensures clarity in the field picker for finance metrics."
    select: "view.dimension"
    filters:
      view_label: "Finance"
    match: "^fin_[a-z0-9_]+$"

  # 2. Pattern Match: Forbid draft or test views
  - name: forbid-draft-views
    title: "Views cannot be named with draft_ or test_ prefixes"
    rule_type: pattern_match
    severity: error
    select: "view"
    should_not_match: "^(draft|test)_.*"

  # 3. Property: Require explicit relationship on joins
  - name: require-join-relationship
    title: "All joins must declare an explicit relationship"
    rule_type: property
    severity: error
    select: "explore.join"
    requires_child: "relationship"

  # 4. Property: Explores must not use sql_always_where
  - name: forbid-sql-always-where
    title: "Explores should use always_filter instead of sql_always_where"
    rule_type: property
    severity: warn
    select: "explore"
    forbidden_child: "sql_always_where"

  # 5. Order: Dimension groups inside views must be alphabetical
  - name: view-dimension-groups-alphabetical
    title: "Dimension groups must appear in alphabetical order within views"
    rule_type: order
    severity: warn
    select: "view"
    order_by: "dimension_group"

  # 6. First Child: Primary key must be the first dimension
  - name: custom-primary-key-first-dimension
    title: "The primary key must be defined as the first dimension in the view"
    rule_type: first_child
    severity: error
    select: "view.dimension"
    filters:
      primary_key: true
    position: first

  # 7. Unique: Views must not share the same label
  - name: unique-view-labels
    title: "Views must have unique labels"
    rule_type: unique
    severity: warn
    select: "view"
    unique_property: "label"

היקף האימות ותוצאות האימות

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

קבצים שאומתו

  • רק קבצים מסוג .lkml ו-.lookml בפרויקט הבסיסי עוברים אימות. פרויקטים של תלות (מקומיים או מרוחקים) שיובאו לא עוברים אימות.
  • כל קובץ עובר אימות על סמך התוכן שלו. ההצהרות include: לא מבוצעות, והאובייקטים שנמשכים באמצעות הצהרה include: לא מאומתים כחלק מהקובץ המצורף.
  • הפעלות CI שמופעלות על ידי משימות CI ב-dbt Cloud מאמתות את הסתעפות הייצור של LookML ולא את הסתעפות הפיתוח.

התנהגות ופלט של מעבר או כשל

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

אימות מצטבר

כדי להפעיל אימות מצטבר של הכלי Style Validator, מסמנים את תיבת הסימון Only incremental errors (מופעלת כברירת מחדל) בקטע Style Validator כשיוצרים או עורכים חבילת בדיקות של אינטגרציה רציפה (CI).

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

  1. הוא מאמת את ענף הפיתוח.
  2. הכלי מאמת את ענף היעד באמצעות קובץ התצורה של ענף הפיתוח.
  3. הוא מדווח רק על ההפרות שלא קיימות כבר בענף היעד.

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

  • הפרות קיימות בענף היעד לא גורמות לריצה להיכשל.
  • קובץ התצורה של ענף הפיתוח משמש לאימות של שני הענפים, ולכן שינוי בתצורה של ענף הפיתוח לא יכול להסתיר הפרות קיימות או לגרום ל-LookML קיים להופיע כהפרות חדשות.
  • ענף הפיתוח חייב להכיל קובץ תצורה lkmlstyle.yaml (או lkmlstyle.yml), אחרת ההרצה תיכשל עם שגיאה של תצורה חסרה.

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

קטלוג של כללים מובנים

בטבלה הבאה מפורטים כל 25 הכללים המובנים הרגילים שזמינים בערכת הכללים all-v1.0:

שם הכלל ישות היעד סיכום הכלל
average-measure-name-prefix מדידה מדדים עם type: average או average_distinct חייבים להתחיל ב-avg_ או ב-average_.
boolean-dimension-name-prefix מאפיין מאפיינים מסוג Yesno חייבים להתחיל ב-is_, ב-has_ או ב-does_.
count-measure-name-prefix מדידה מדדים עם type: count או count_distinct חייבים להתחיל ב-count_.
dimension-group-name-suffix קבוצת מאפיינים קבוצות מאפיינים לא יכולות להסתיים ב-_at, ב-_date או ב-_time.
dimension-label-redundant-yes-no מאפיין תוויות של מאפיינים מסוג Yes/No לא יכולות לכלול סמן של Yes/No כמו (Yes / No) או (yes/no) (בכל שימוש באותיות רישיות או ברווחים).
dimension-name-snake-case מאפיין שמות המאפיינים וקבוצות המאפיינים צריכים להיות באותיות קטנות snake_case.
explore-fields-presence שלב שני ב-Explores צריך להגדיר את המאפיין fields:.
explore-label-presence שלב שני בדוחות ניתוח צריך להגדיר מאפיין label: מפורש.
includes-wildcard-usage הכללה include: בדפי חשבון אסור להשתמש בתווים כלליים לצפייה בקבצים (כמו *.view.lkml או /views/*.view). תווים כלליים אחרים לא מסומנים.
join-relationship-presence הצטרפות הצהרות Explore join: חייבות לציין relationship:.
measure-name-snake-case מדידה שמות המדדים צריכים להיות באותיות קטנות snake_case.
measure-sql-table-reference מדידה במדדים צריך להפנות למאפיינים באמצעות ${dimension_name}, ולא באמצעות ${TABLE}.column.
numeric-measure-value-format-presence מדידה במידות עם type: count,‏ sum,‏ average או number צריך לציין value_format: או value_format_name:.
pdt-view-name-prefix הצגה טבלאות נגזרות מתמידות (PDT) צריכות להתחיל ב-pdt_. תצוגה נחשבת ל-PDT אם השדה derived_table שלה מגדיר את datagroup_trigger,‏ sql_trigger_value,‏ interval_trigger או persist_for, או מגדיר את materialized_view: yes.
primary-key-first-dimension מאפיין המאפיין של המפתח הראשי חייב להיות המאפיין הראשון שמוגדר בתצוגה המפורטת.
primary-key-visibility מאפיין צריך להסתיר את המימדים של המפתח הראשי (hidden: yes).
sql-table-name-uniqueness הצגה כמה תצוגות לא יכולות להפנות לאותו sql_table_name.
sum-measure-name-prefix מדידה מדדים עם type: sum או sum_distinct חייבים להתחיל ב-sum_ או ב-total_.
view-dimension-order הצגה המימדים בתצוגה צריכים להיות מסודרים בסדר אלפביתי.
view-label-presence הצגה בתצוגות צריך להגדיר label: מפורש.
view-measure-order הצגה המדדים בתצוגה צריכים להיות מסודרים בסדר אלפביתי.
view-name-snake-case הצגה שמות התצוגות צריכים להיות באותיות קטנות snake_case (מותר להשתמש בתו + בתחילת השם של שיפורים).
view-primary-key-presence הצגה בתצוגות עם sql_table_name או derived_table (ובלי extends) צריך להגדיר מפתח ראשי.
visible-dimension-description-presence מאפיין למידות הגלויות צריך להיות ערך description:.
visible-measure-description-presence מדידה למדדים גלויים צריך להיות description:.

פתרון בעיות

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

שגיאות בהגדרות

הבעיות הבאות נדחות כשקובץ התצורה נטען, והן מדווחות כשגיאת invalid-config:

  • מפתחות לא ידועים ברמה העליונה או מפתחות לא ידועים בתוך הגדרת כלל.
  • חסר הפרמטר schema_version או ruleset_version, או שערך הפרמטר לא נתמך.
  • חומרות סקלריות בקיצור, כמו rule-name: warn.
  • חסימת שינוי ברירת המחדל עם files או rules חסרים או ריקים, או הגדרת כלל בתוך חסימת שינוי ברירת המחדל בלי severity.
  • שם כלל לא ידוע בבלוק של ביטול.
  • כלל מותאם אישית שהשם שלו זהה לשם של כלל מותאם אישית אחר או כלל מובנה.
  • מפתח ספציפי לסוג מסוים שנעשה בו שימוש לא נכון ב-rule_type (לדוגמה, order_by בכלל pattern_match).
  • ביטוי רגולרי לא תקין.
  • חסר הפרמטר order_by (לכללי order) או הפרמטר unique_property (לכללי unique).
  • ערך position שונה מ-first (לכללי first_child).
  • תו ! מוביל ללא מרכאות במפתח של מסנן, כמו !hidden: true, שהוא תחביר לא תקין של תג YAML וגורם לכשל בניתוח של קובץ תצורה.

בעיות בהגדרות שקטות

  • המערכת מתעלמת בשקט משמות כללים עם שגיאות כתיב בבלוק rules הגלובלי.
  • אם יש שגיאות כתיב בשמות של סוגי LookML בשדות select, filters, parent_filters, requires_child, forbidden_child או order_by, לא מוצגת שגיאה. במקום זאת, הכלל אף פעם לא תואם (או שב-requires_child, הוא תמיד נכשל).
  • אם מציינים גם את match וגם את should_not_match, או גם את requires_child וגם את forbidden_child: המערכת מתייחסת רק לפרמטר הראשון בכל זוג ומתעלמת מהפרמטר השני.
  • הגדרה של parent_filters בכלל first_child לא משפיעה והמערכת מתעלמת ממנה.
  • המסננים תואמים רק למאפיינים שמוצהרים באופן מפורש בקובץ LookML, ולא לערכי ברירת המחדל של LookML (ראו תחביר הסינון).
  • דפוסי ביטויים רגולריים בכללי pattern_match הם התאמות של מחרוזות משנה לא מעוגנות, אלא אם מעגנים אותן באמצעות ^ ו-$ (ראו pattern_match).

וריאציות קבילות של תחביר

  • הערכים של severity ושל rule_type לא תלויי-רישיות.
  • הכתובת rule_type: pattern מתקבלת ככתובת אימייל חלופית לכתובת pattern_match.
  • המערכת מתעלמת מרווחים בתחילת השורה או בסופה ב-ruleset_version.