定價
登入 開始使用
文件 學習
首頁
分析
嵌入
管理
其他資源

驅動程式介面變更日誌

Metabase 0.54.0

  • 新增了 :test/arrays 功能和 native-array-query 多方法，以便為支援陣列類型的資料庫啟用陣列類型測試。

Metabase 0.53.0

  • 新增了 bad-connection-details 多方法，以允許模擬用於測試的錯誤連線參數。

Metabase 0.52.0

  • Metabase 0.52.0 的 Docker 映像檔現在使用 Java 21 而不是 Java 11。請務必針對 Java 21 測試您的驅動程式，並確保它能如預期般運作。

    我們發現我們自己的幾個驅動程式在較新 JVM 中引入的安全性變更時遇到問題；因此，我們目前正在設定 JVM 標誌

    --add-opens java.base/java.nio=ALL-UNNAMED

    在執行 Metabase 時停用其中一些新的安全性檢查。如果您的測試在未設定標誌的情況下於 Java 21 中執行時遇到問題，請嘗試在設定標誌的情況下執行 - 這可能會解決問題。

Metabase 0.51.4

  • 已新增另一個驅動程式功能：:describe-indexes。如果驅動程式選擇支援此功能，則必須實作多方法 metabase.driver/describe-indexes，以取代 metabase.driver/describe-table-indexes。

  • 已新增多方法 metabase.driver.sql-jdbc.sync.describe-table/describe-indexes-sql。如果驅動程式支援 :describe-indexes 且您想要使用 metabase.driver/describe-indexes 的預設 JDBC 實作，則需要實作此方法。

Metabase 0.51.0

  • 新增了新的選用方法 metabase.driver/query-result-metadata，用於有效率地計算查詢的元數據，而無需實際執行查詢。:sql-jdbc 已獲得預設實作；不基於此且可以在不實際執行查詢的情況下判斷結果元數據的驅動程式也應新增其各自的實作，以便在儲存問題時獲得更好的效能。請參閱方法文件字串以取得更多資訊，以及在哪裡可以找到範例實作。

  • 在 0.51.0 之前的版本中，為了產生帶有內聯參數的 SQL 查詢，Metabase 會產生參數化的 SQL 字串，然後嘗試解析 SQL replace 並使用驅動程式方法 metabase.driver.sql.util.unprepare/unprepare-value 中的內聯值取代 ? 佔位符。在 0.51.0+ 版本中，Metabase 改為使用 Honey SQL 2 的 :inline 選項產生這些查詢，從而無需解析和取代 ? 佔位符。因此，metabase.driver.sql.util.unprepare 命名空間已被棄用；您應該移除驅動程式中所有對它的使用。

  • metabase.driver.sql.util.unprepare/unprepare-value 方法已由新方法 metabase.driver.sql.query-processor/inline-value 取代。這兩個函式的簽名相同，您應該能夠簡單地將所有 unprepare-value 實作變更為 inline-value。請參閱 PR #45008 以取得此變更的範例。

    暫時，unprepare-value 的實作會自動用作 inline-value 的實作，但 unprepare-value 計劃在 0.54.0 版本中移除。

  • metabase.driver.sql.query-processor/format-honeysql 現在是一個多方法，主要是為了讓您在需要始終在不進行參數化的情況下編譯時可以綁定 *compile-with-inline-parameters*。

  • 已新增動態變數 metabase.driver/*compile-with-inline-parameters* (預設值為 false)；可以產生參數化查詢的驅動程式應查看其在 metabase.driver/mbql->native 實作中的值，並相應地調整其輸出。對於支援參數化的基於 :sql-jdbc 的驅動程式，這在共用的 metabase.driver.sql.query-processor 程式碼中處理，因此您無需在此處進行任何調整。對於不支援 JDBC 樣式參數化查詢的 :sql 驅動程式，您可以實作 format-honeysql 並如上所述綁定 *compile-with-inline-parameters*。請參閱 :athena 驅動程式以取得如何執行此操作的範例。

  • metabase.driver.sql.util.unprepare/unprepare 已被移除，它接受一個參數化的 SQL 字串並對其進行去參數化或「未準備」。相反，如果您需要一個參數直接拼接在 SQL 中的查詢，請如上所述綁定 metabase.driver/*compile-with-inline-parameters*。

  • 同樣地，驅動程式方法 metabase.driver/splice-parameters-into-native-query 已被標記為已棄用，並且如果調用，預設實作將會拋出異常。重構產生參數化查詢，然後調用 unprepare 或 splice-parameters-into-native-query 的程式碼，並使用首先產生帶有內聯參數的查詢的程式碼，如上所述。如果需要，測試可以使用 metabase.query-processor.compile/compile-with-inline-parameters。

  • metabase.query-processor.compile/compile-and-splice-parameters 已被移除；將用法替換為 metabase.query-processor.compile/compile-with-inline-parameters。

  • metabase.driver.sql.query-processor/format-honeysql 的三元數 (具有 Honey SQL 版本的額外參數) 已被移除；將所有用法替換為二元數版本。自 Metabase 0.49.0 以來，Honey SQL 2 一直是唯一支援的版本。

  • 有時傳遞給用於載入和銷毀測試資料的方法的 :skip-drop-db? 選項不再傳遞，您可以移除檢查它的程式碼。測試資料程式碼現在可以更好地避免不必要的/多餘的 metabase.test.data.interface/create-db! 呼叫，因此測試資料載入程式碼在載入測試資料之前不需要調用 DROP DATABASE IF EXISTS。

  • 基於 JDBC 的資料庫的測試資料載入已進行了一些修改。多方法 metabase.test.data.sql-jdbc.load-data/load-data! 及其輔助函式已被移除，取而代之的是幾個新的更易於組合和理解的多方法。

  • metabase.test.data.sql-jdbc.load-data/row-xform 是一個轉換器，在載入測試資料時應用於每一列。預設實作是 identity，但您可以使用 metabase.test.data.sql-jdbc.load-data/add-ids-xform 將 ID 新增至每一列 (這取代了已移除的 metabase.test.data.sql-jdbc.load-data/load-data-add-ids 函式) 和 metabase.test.data.sql-jdbc.load-data/maybe-add-ids-xform (它取代了 metabase.test.data.sql-jdbc.load-data/load-data-maybe-add-ids! 和 metabase.test.data.sql-jdbc.load-data/load-data-maybe-add-ids-chunked!)。

  • metabase.test.data.sql-jdbc.load-data/chunk-size 用於控制每個批次中應載入的列數。預設值為 200，但您可以實作此方法並傳回 nil 以一次載入所有資料，而不管列數多少。metabase.test.data.sql-jdbc.load-data/*chunk-size*、metabase.test.data.sql-jdbc.load-data/load-data-chunked、metabase.test.data.sql-jdbc.load-data/load-data-all-at-once!、metabase.test.data.sql-jdbc.load-data/load-data-chunked! 和其他類似函式不再需要且已被移除。

  • metabase.test.data.sql-jdbc.load-data/chunk-xform 是一個轉換器，應用於每批列 (取決於 chunk-size) 或整組列 (如果 chunk-size 為 nil)。預設值為 identity。它可以用於為每個批次實作特殊行為，例如將批次寫入 CSV 檔案，以便在 metabase.test.data.sql-jdbc.load-data/do-insert! 方法中單獨載入。請參閱 metabase.test.data.vertica 以取得範例。

  • 連線現在建立一次，並在大部分測試資料載入中重複使用。metabase.test.data.sql-jdbc.load-data/do-insert! 的第二個引數現在是 java.sql.Connection 而不是 clojure.java.jdbc 規格。

  • 同樣地，metabase.test.data.sql-jdbc.execute/execute-sql! 和輔助函式 (例如 metabase.test.data.sql-jdbc.execute/sequentially-execute-sql!) 現在使用 java.sql.Connection 而不是 DatabaseDefinition 和 :server 或 :db _context_ 來調用；適當的連線類型會自動建立並在調用程式碼中傳遞。請相應地更新您的方法實作和用法。

  • 新增了方法 metabase.test.data.interface/dataset-already-loaded? 以檢查是否已載入測試資料集。基於 JDBC 的驅動程式具有預設實作，可檢查我們是否可以連線到資料庫；對於實際上未在測試中實際建立新資料庫的驅動程式，您可能需要覆寫此方法。您可以使用預設實作來檢查基於 JDBC 的驅動程式是否正常運作，方法是執行測試 metabase.test.data.sql-jdbc-test/dataset-already-loaded?-test。

  • metabase.test.data.sql.ddl/insert-rows-ddl-statements 已重新命名為 metabase.test.data.sql.ddl/insert-rows-dml-statements，因為 INSERT 是 DML，而不是 DDL。請相應地更新您的方法實作。

  • :foreign-keys 驅動程式功能已被移除。:metadata/keys-constraints 應適用於在同步期間支援外鍵關係報告的驅動程式。隱式聯結現在改為依賴 :left-join 功能。對於基於 :sql 的驅動程式，預設值為 true。所有聯結功能現在預設為基於 :sql 的驅動程式啟用。先前，這些功能依賴於 :foreign-keys 功能。如果您的驅動程式支援 :left-join，則現在將執行重新映射和隱式聯結的測試。

  • The:parameterized-sql 驅動程式功能已新增，以區分在測試中不支援參數化 SQL 的驅動程式。目前，這僅針對 :sparksql 停用。

  • 測試方法 metabase.test.data.interface/supports-time-type? 和 metabase.test.data.interface/supports-timestamptz-type? 已被移除，並分別由功能 :test/time-type 和 :test/timestamptz-type 取代。如果您實作了這些方法，請將實作替換為驅動程式的 metabase.driver/database-supports? 實作和等效的功能關鍵字。

  • 使用 metabase.driver.sql.query-processor/->honeysql 的驅動程式可以實作 :metabase.driver.sql.query-processor/nfc-path，以在欄位識別碼中包含 nfc-path。以便可以使用 <table>.<record>.<record-field> 參考類似記錄的欄位。請參閱 bigquery-cloud-sdk 以取得範例。預設為 nil，表示路徑不應成為識別碼的一部分。

  • 已新增 :test/dynamic-dataset-loading 功能。它使驅動程式能夠退出需要在測試執行時建立新的、未預先載入的資料集的測試。

  • 已新增 :temporal/requires-default-unit 功能。對於大多數驅動程式來說，它應該為 false，但對於少數驅動程式 (例如舊的、pre-JDBC Druid 驅動程式) 來說，它必須找到所有時間欄位參考並在其上放置 :temporal-unit :default。該預設設定先前已針對所有驅動程式完成，但它引入了一些下游問題，因此現在只有那些需要它的驅動程式才能設定該功能。

Metabase 0.50.17

  • 新增了方法 metabase.driver/incorporate-auth-provider-details，用於驅動程式特定的行為，以便將身份驗證提供者的回應併入 DB 詳細資訊中。在大多數情況下，這表示根據身份驗證提供者及其回應設定 :password 和/或 :username。

Metabase 0.50.16

  • :type/fingerprinting-unsupported 已在 metabase.types 命名空間中新增。與用於欄位值掃描的 :type/field-values-unsupported 類似，它用於判斷是否應計算特定欄位的指紋。在撰寫本文時，該邏輯在 metabase.sync.analyze.fingerprint/fields-to-fingerprint-base-clause 中執行。

  • :type/Large 也已在 metabase.types 命名空間中新增。驅動程式作者可以使用它來表示特定欄位包含足夠大的值，可以跳過指紋或欄位值掃描。將來它也可以用於其他目的。範例包括 Oracle CLOB 或 Postgres JSON 欄。

Metabase 0.50.0

  • Metabase 的 metabase.mbql.* 命名空間已移至 metabase.legacy-mbql.*。您可能不需要在驅動程式中使用這些命名空間，但如果您有使用，請更新它們。

  • 已新增多重方法 metabase.driver/truncate!。此方法用於以最有效率的方式刪除表格的列。目前僅支援 :uploads 功能的驅動程式需要此方法，並且 JDBC 基礎的驅動程式具有預設實作。

  • 已新增新功能 :window-functions/cumulative。實作此方法的驅動程式應在其原生查詢語言中實作累加總和 (:cum-sum) 和累加計數 (:cum-count) 聚合子句。對於非 SQL 驅動程式（非基於我們的 :sql 或 :sql-jdbc 驅動程式的驅動程式），此功能標誌預設設定為 false；將繼續使用舊的（已損壞的）累加聚合後處理實作。（有關舊實作為何損壞的更多資訊，請參閱問題 #13634 和 #15118。）

    如果可能，應更新非 SQL 驅動程式以原生實作累加聚合。

    SQL 實作使用 OVER (...) 運算式。它會自動將 GROUP BY 運算式（如 date_trunc()）移至 SUBSELECT 中，以便像 BigQuery 這樣挑剔的資料庫可以參考純資料行識別碼。實際產生的 SQL 看起來會像這樣

    SELECT
  created_at_month,
  sum(sum(total) OVER (ORDER BY created_at_month ROWS UNBOUNDED PRECEDING) AS cumulative_sum
FROM (
  SELECT
    date_trunc('month', created_at) AS created_at_month,
    total
  FROM
    my_table
  ) source
GROUP BY
  created_at_month
ORDER BY
  created_at_month

    如果非 SQL 驅動程式想要利用相同的查詢轉換，可以使用 metabase.query-processor.util.transformations.nest-breakouts/nest-breakouts-in-stages-with-window-aggregation。如需在需要時使用此轉換的範例，請參閱 :sql 的預設 metabase.driver.sql.query-processor/preprocess 實作。

    您可以執行 metabase.query-processor-test.cumulative-aggregation-test 中的新測試，以驗證您的驅動程式實作是否正常運作。

  • metabase.driver.common/class->base-type 不再支援 Joda Time 類別。它們自 2019 年起已棄用。

  • 已新增新功能 :window-functions/offset，以表示驅動程式支援新的 MBQL :offset 子句（相當於 SQL lead 和 lag 函數）。對於基於 :sql 和 :sql-jdbc 的驅動程式，預設啟用此功能。其他驅動程式應為此子句新增實作並啟用功能標誌。

  • :type/field-values-unsupported 已新增至 metabase.types 命名空間。它用於欄位值計算邏輯中，以判斷特定欄位是否應計算其欄位值。在撰寫本文時，此操作在 metabase.models.field-values/field-should-have-field-values? 中執行。從中衍生，驅動程式開發人員可以針對與用於計算的查詢不相容的欄位，選擇不進行欄位值計算。例如，Druid 的 COMPLEX<JSON> 資料庫類型欄位。如需範例，請參閱 metabase.driver.druid-jdbc 中 sql-jdbc.sync/database-type->base-type 的 :druid-jdbc 實作以及 metabase.types 命名空間中的衍生。

  • 已新增新功能 :metadata/key-constraints，以表示驅動程式支援在結構描述層級定義和強制執行外鍵約束。這是一個與 :foreign-keys 不同的更強條件。某些資料庫（Presto、Athena 等）支援查詢外鍵關係 (:foreign-keys)，但不追蹤或強制執行結構描述中的這些關係。在 :sql 和 :sql-jdbc 驅動程式中預設為 true；在第一方 SparkSQL、Presto 和 Athena 驅動程式中設定為 false。

  • 已新增新功能 :connection/multiple-databases，以指出此驅動程式的連線是對應至多個資料庫還是僅對應至一個資料庫。預設值為 false，其中連線指定單一資料庫。這是傳統關聯式資料庫（如 Postgres）和某些雲端資料庫的常見情況。相反地，像 Athena 這樣的驅動程式會將此設定為 true，因為它連線到 S3 儲存貯體，並將其中的每個檔案視為一個資料庫。

  • 已新增新功能 :identifiers-with-spaces，以指出驅動程式在何處支援包含空格字元的識別碼，例如表格或資料行名稱。預設值為 false。

  • 已新增新功能 :uuid-type，以指出此資料庫能夠區分 UUID 並根據 UUID 進行篩選。只有少數資料庫支援原生 UUID 類型。預設值為 false。

Metabase 0.49.22

  • 已新增新的選用方法 metabase.driver.sql/json-field-length。對於所有衍生自 :sql 並支援 :nested-field-columns 功能的驅動程式，都應實作此方法。如果已實作，Metabase 將在「同步欄位」步驟中跳過查詢大型 JSON 值，否則可能會減慢巢狀欄位資料行的推斷速度，並導致 Metabase 耗盡堆積空間。

Metabase 0.49.9

  • 已新增另一個驅動程式功能：upload-with-auto-pk。它僅影響支援 uploads 的驅動程式，並且支援是選用的。驅動程式預設支援此功能，如果無法建立具有自動遞增整數資料行的表格，則可以選擇不支援此功能。驅動程式可以使用 driver/database-supports? 覆寫預設值。

Metabase 0.49.1

  • 已新增另一個驅動程式功能：describe-fields。如果驅動程式選擇加入支援此功能，則必須實作多重方法 metabase.driver/describe-fields，以取代 metabase.driver/describe-table。

  • 已新增多重方法 metabase.driver.sql-jdbc.sync.describe-table/describe-fields-sql。如果驅動程式支援 describe-fields，並且您想要使用 metabase.driver/describe-fields 的預設 JDBC 實作，則需要實作此方法。

Metabase 0.49.0

  • 多重方法 metabase.driver/describe-table-fks 已棄用，改用 metabase.driver/describe-fks。metabase.driver/describe-table-fks 將在 0.52.0 中移除。

  • 已新增多重方法 metabase.driver/describe-fks。如果資料庫支援 :foreign-keys 和 :describe-fks 功能，則需要實作此方法。它取代了現在已棄用的 metabase.driver/describe-table-fks 方法。

  • 已新增多重方法 metabase.driver.sql-jdbc.sync.describe-table/describe-fks-sql。如果您想要使用 metabase.driver/describe-fks 的預設 JDBC 實作，則需要實作此方法。

  • 已新增多重方法 metabase.driver/alter-columns!。此方法用於變更資料庫中表格的資料行。目前僅支援 :uploads 功能的驅動程式需要此方法，並且 JDBC 基礎的驅動程式具有預設實作。

  • 已新增多重方法 metabase.driver.sql-jdbc.sync.interface/alter-columns-sql。此方法可讓您自訂 metabase.driver/alter-columns! 的預設 JDBC 實作所使用的查詢。

  • 已新增多重方法 metabase.driver.sql-jdbc.sync.interface/current-user-table-privileges。基於 JDBC 的驅動程式可以實作此方法，以改善 metabase.driver/describe-database 的預設 SQL JDBC 實作的效能。如果資料庫支援 :table-privileges 功能，且驅動程式是以 JDBC 為基礎，則需要實作此方法。

  • 多重方法 metabase.driver/create-table! 可以採用額外的選用地圖，其中包含選用鍵 primary-key。metabase.driver/upload-type->database-type 也必須變更，以便在提供 :metabase.upload/auto-incrementing-int-pk 作為 upload-type 引數時，函數應傳回不包含主鍵約束的類型。如需更多資訊，請參閱 PR #22166。只有在資料庫支援 :uploads 功能時，才需要實作這些變更。

  • 已新增多重方法 metabase.driver/create-auto-pk-with-append-csv?。只有在資料庫在 47 或更早版本中支援 :uploads 功能時，才需要實作此方法，如果是，則應傳回 true。

  • 已新增多重方法 metabase.driver/add-columns!。此方法用於將資料行新增至資料庫中的表格。只有在資料庫在 47 或更早版本中支援 :uploads 功能時，才需要實作此方法。

  • 已新增新的驅動程式方法 metabase.driver/describe-table-indexes 以及新功能 :index-info。此方法用於取得已建立索引或作為複合索引中第一個資料行的資料行名稱集合。

  • 已移除在 0.46.0 中棄用的 metabase.util.honeysql-extensions。不再支援使用 Honey SQL 1 的 SQL 基礎驅動程式。如需更多資訊，請參閱 0.46.0 筆記。metabase.driver.sql.query-processor/honey-sql-version 現在已棄用，且不再呼叫。假設所有驅動程式都使用 Honey SQL 2。

  • 方法 metabase.driver.sql.parameters.substitution/align-temporal-unit-with-param-type 現在已棄用。請改用 metabase.driver.sql.parameters.substitution/align-temporal-unit-with-param-type-and-value，它可以存取 value，因此可以更靈活地選擇正確的轉換單位。

Metabase 0.48.0

  • metabase.mbql.schema 中的 MBQL 結構描述現在使用 Malli 而非 Schema。如果您將此命名空間與 Schema 結合使用，則會想要更新您的程式碼以改用 Malli。

  • 已新增另一個驅動程式功能：:table-privileges。此功能表示我們是否可以在資料庫同步時儲存資料庫的表格層級權限。

  • 已新增多重方法 metabase.driver/current-user-table-privileges。此方法用於取得資料庫連線目前使用者擁有的權限集合。如果資料庫支援 :table-privileges 功能，則需要實作此方法。

  • metabase.query-processor.store (qp.store) 中的下列函數現在已棄用

    • qp.store/database
    • qp.store/table
    • qp.store/field

    將用法更新為 metabase.lib.metadata (lib.metadata) 中的對應函數

    (qp.store/database)       => (lib.metadata/database (qp.store/metadata-provider))
(qp.store/table table-id) => (lib.metadata/table (qp.store/metadata-provider) table-id)
(qp.store/field field-id) => (lib.metadata/field (qp.store/metadata-provider) field-id)

    請注意，新方法會以 kebab-case 而非 snake_case 傳回索引鍵。

  • 同樣地，驅動程式不應直接存取應用程式資料庫（透過 toucan 函數或其他方式）；請改用 lib.metadata 函數。此存取可能會在未來的版本中遭到封鎖。

  • 針對 metabase.models.table/Table/:model/Table 實作 metabase.driver.sql.query-processor/->honeysql 的 SQL 驅動程式應更新為針對 :metadata/table 實作。與上述變更一樣，主要差異在於新的中繼資料對應使用 kebab-case 索引鍵，而非 snake_case 索引鍵。

  • metabase.driver.sql.query-processor/cast-field-if-needed 現在預期 lib.metadata/field 傳回的 kebab-case 欄位。

  • 已移除 metabase.query-processor.store/fetch-and-store-database!、metabase.query-processor.store/fetch-and-store-tables! 和 metabase.query-processor.store/fetch-and-store-fields!。現在會根據需要自動擷取內容，這些呼叫已不再必要。

  • 已移除 metabase.models.field/json-field?，請改用 metabase.lib.field/json-field?。請注意，新函數會採用 lib.metadata/field 傳回的欄位，即 kebab-case 對應。

  • 測試應嘗試避免使用任何 with-temp 協助程式或應用程式資料庫物件；請改用上述中繼資料函數和 metabase.lib、metabase.lib.test-util 和 metabase.query-processor.test-util 中的協助程式中繼資料提供者來模擬它們，例如 mock-metadata-provider、metabase-provider-with-cards-for-queries、remap-metadata-provider 和 merged-mock-metadata-provider。

  • metabase.query-processor.util.add-alias-info/field-reference 現在已棄用。如果您的驅動程式已實作，請改為實作 metabase.query-processor.util.add-alias-info/field-reference-mlv2。兩者之間唯一的差異在於後者傳遞具有 kebab-case 索引鍵的欄位中繼資料，而前者傳遞具有 snake_case 索引鍵的舊版中繼資料。

  • 已移除在 0.34 中棄用的 metabase.driver/current-db-time，以及相關方法和協助程式函數。請改為實作 metabase.driver/db-default-timezone。

  • 已棄用用於為 JDBC 基礎驅動程式撰寫 metabase.driver/db-default-timezone 實作的協助程式 metabase.driver.sql-jdbc.sync.interface/db-default-timezone，並將在 0.51.0 或更新版本中移除。您可以輕鬆地直接實作 metabase.driver/db-default-timezone，並使用 metabase.driver.sql-jdbc.execute/do-with-connection-with-options 來取得資料庫的 java.sql.Connection。

  • 新增了新的多重方法 metabase.driver.sql.parameters.substitution/align-temporal-unit-with-param-type，它會針對 field、param-type 和給定的驅動程式傳回合適的時間單位轉換關鍵字。產生的關鍵字將用於呼叫對應的 metabase.driver.sql.query-processor/date 實作，以轉換 field。如果此 field 和 param-type 組合不需要轉換，則傳回 nil。

  • 已新增多重方法 metabase.driver.sql-jdbc.execute/inject-remark。它允許 JDBC 基礎驅動程式覆寫如何將 SQL 查詢備註新增至查詢的預設行為（將其作為註解前置）。

  • 多重方法 metabase.driver.sql-jdbc.sync.interface/fallback-metadata-query 的引數數量已從 3 個更新為 4 個，現在它採用額外的 db 引數。新函數引數為：[driver db-name-or-nil schema table]。

Metabase 0.47.0

  • 已新增新的驅動程式功能：:schemas。此功能表示資料庫是否在結構描述（也稱為命名空間）中組織表格。大多數資料庫都有結構描述，因此預設會開啟此功能。只有在資料庫未將表格儲存在結構描述中時，才需要針對 :schemas 實作多重方法 metabase.driver/database-supports?。

  • 已新增另一個驅動程式功能：:uploads。:uploads 功能表示資料庫是否支援將 CSV 檔案上傳到資料庫中的表格。若要支援上傳功能，請實作下列新的多重方法：metabase.driver/create-table!（建立表格）、metabase.driver/drop-table!（捨棄表格）和 metabase.driver/insert-into!（將值插入表格）。

  • 已新增多重方法 metabase.driver/syncable-schemas。此方法用於列出要將 CSV 上傳到的結構描述，且應包含所有可以同步的結構描述。目前，只有在資料庫具有結構描述且資料庫支援 :uploads 功能時，才需要實作此方法。

  • metabase.driver/supports? 已棄用，改用 metabase.driver/database-supports?。database-supports? 的現有預設實作目前會呼叫 supports?，但將在 0.50.0 中移除。

  • metabase.driver.sql-jdbc.execute/connection-with-timezone 已標記為已棄用，並排定在 Metabase 0.50.0 中移除。新的方法 metabase.driver.sql-jdbc.execute/do-with-connection-with-options 取代了它。移轉到新方法很簡單。如需更多資訊，請參閱 PR #22166。您應該使用 metabase.driver.sql-jdbc.execute/do-with-connection-with-options 而非 clojure.java.jdbc/with-db-connection 或 clojure.java.jdbc/get-connection。

  • 已新增多重方法 set-role!、set-role-statement 和 default-database-role。這些方法用於啟用連線模擬，這是 0.47.0 中新增的新功能。連線模擬允許將使用者指派給特定的資料庫角色，這些角色會在執行任何查詢之前設定，以便可以在資料庫層級（而不是或結合 Metabase 的內建權限系統）限制對表格的存取。

  • 多重方法 metabase.driver.sql-jdbc.sync.describe-table/get-table-pks 已變更為傳回向量，而非集合。

  • 函數 metabase.query-processor.timezone/report-timezone-id-if-supported 已更新為針對先前具有一個引數的引數數量採用額外的 database 引數。此函數可能會在驅動程式的多重方法實作中使用。

  • 新增了 metabase.driver/prettify-native-form，以讓驅動程式開發人員使用特定於其驅動程式的原生表單格式設定。如需詳細資訊，請參閱 PR #34991。

Metabase 0.46.0

  • 在 Metabase 0.46.0 中，建置驅動程式的程序稍有變更。您的建置命令現在應如下所示

    # Example for building the driver with bash or similar

# switch to the local checkout of the Metabase repo
cd /path/to/metabase/repo

# get absolute path to the driver project directory
DRIVER_PATH=`readlink -f ~/sudoku-driver`

# Build driver. See explanation in sample Sudoku driver README
clojure \
  -Sdeps "{:aliases {:sudoku {:extra-deps {com.metabase/sudoku-driver {:local/root \"$DRIVER_PATH\"}}}}}"  \
  -X:build:sudoku \
  build-drivers.build-driver/build-driver! \
  "{:driver :sudoku, :project-dir \"$DRIVER_PATH\", :target-dir \"$DRIVER_PATH/target\"}"

    請查看我們的 範例 Sudoku 驅動程式的建置指示，以瞭解命令的說明。

    請注意，雖然此命令本身輸入量相當大，但您不再需要在驅動程式的 deps.edn 檔案中指定 :build 別名。

    請為 https://ask.clojure.org/index.php/7843/allow-specifying-aliases-coordinates-that-point-projects 投贊成票，這將讓我們在未來簡化驅動程式建置命令。

  • 已新增多重方法 metabase.driver/table-rows-sample。此方法用於 Metabase 需要表格的有限範例的情況，例如在指紋識別時。metabase.db.metadata-queries 命名空間中定義的預設實作會執行 MBQL 查詢，使用一般查詢處理器來產生範例列。在大多數情況下，這已足夠，因此除非真的必要，否則不應實作此多重方法。目前，唯一使用特殊實作的情況是 BigQuery，它不遵守限制子句。

  • 已新增多重方法 metabase.driver.sql.query-processor/datetime-diff。此方法由 :datetime-diff 子句的 ->honeysql 實作使用。如果您想要使用 :datetime-diff 的預設 SQL 實作，建議實作此方法，其中包括跨所有單位的引數類型驗證。

  • 已新增多重方法 metabase.query-processor.util.add-alias-info/field-reference。此方法用於由 add-alias-info 中介軟體產生欄位的參考。（請注意，此中介軟體是選用的，目前僅由 SQL 和 MongoDB 驅動程式使用。）預設實作會傳回欄位執行個體的名稱。如果僅名稱不是有效的參考，則應覆寫它。例如，MongoDB 支援巢狀文件，且巢狀欄位的參考應包含完整路徑。如需替代實作，請參閱命名空間 metabase.driver.mongo.query-processor。

  • 已移除在 0.43.0 中棄用的多重方法 metabase.driver.sql-jdbc.sync.interface/syncable-schemas（別名為 metabase.driver.sql-jdbc.sync/syncable-schemas）。請改為實作 metabase.driver.sql-jdbc.sync.interface/filtered-syncable-schemas。如需更多詳細資訊，請參閱下方的 0.43.0 筆記。

  • 已移除在 0.42.0 中棄用的多重方法 metabase.driver/format-custom-field-name。請改為實作 metabase.driver/escape-alias。如需更多資訊，請參閱下方的 0.42.0 筆記。

  • 已移除在 0.35.0 中棄用的多重方法 metabase.driver.sql-jdbc.execute/read-column。請改為實作 metabase.driver.sql-jdbc.execute/read-column-thunk。如需更多資訊，請參閱下方的 0.35.0 筆記。

Honey SQL 2

以下內容僅適用於 SQL 驅動程式；您可以忽略非 SQL 驅動程式。

在 Metabase 0.46.0 之前，SQL 驅動程式在編譯查詢時使用 Honey SQL 1 作為中繼目標。在 0.46.0 中，我們已開始移轉到 Honey SQL 2 作為我們新的中繼目標的程序。

我們計劃繼續支援使用 Honey SQL 1，直到 Metabase 0.49.0 為止。請務必在那之前移轉您的驅動程式。

在 Metabase 0.46.x、0.47.x 和 0.48.x 中，您可以透過實作 metabase.driver.sql.query-processor/honey-sql-version 多重方法來指定您的驅動程式應使用的 Honey SQL 版本

(require '[metabase.driver.sql.query-processor :as sql.qp])

;;; use Honey SQL 2 for :my-driver
(defmethod sql.qp/honey-sql-version :my-driver
  [_driver]
  2)

此方法必須傳回 1 或 2。目前，預設實作會傳回 1。實際上，這表示您目前必須選擇加入 Honey SQL 2 編譯。最好盡快執行此操作，讓您的驅動程式為 0.49.0 做好充分準備。

在 Metabase 0.47.x 或 0.48.x 中，我們可能會將預設 Honey SQL 版本變更為 2，以確保每個人都知道 0.49.0 中即將發生的重大變更，並讓他們有一個或兩個發行週期來更新其驅動程式以鎖定 Honey SQL 2。在 0.49.0 之前，您仍然可以透過實作 sql.qp/honey-sql-version 並傳回 1 來選擇加入使用 Honey SQL 1。

您需要變更的內容

我們的 Honey SQL 公用程式命名空間 metabase.util.honeysql-extensions（通常別名為 hx）已更新為產生適用於 Honey SQL 1 或 Honey SQL 2 的表單。這是根據您的驅動程式的 honey-sql-version 自動完成的。metabase.driver.sql.query-processor 本身也以相同方式支援這兩個目標。

您需要對驅動程式程式碼進行的實際變更可能相當小。移植驅動程式時最需要注意的事項

  1. 避免使用 Honey SQL 1 命名空間中的項目，例如 honeysql.core 或 honeysql.format。如果您必須使用，請改用 Honey SQL honey.sql；您可能不需要兩者。

  2. 雖然在短期內您可以繼續使用 metabase.util.honeysql-extensions，因為它可以鎖定任何版本的 Honey SQL，但我們可能會在未來某個時間點移除此命名空間。請更新您的程式碼以改用 metabase.util.honey-sql-2。命名空間實作幾乎相同的協助程式函數集，因此您需要切換的只是您在 ns 表單中 :require 的命名空間。

  3. honeysql.core/call 不再存在；您只需傳回純向量（例如 [:my_function 1 2]）即可，而不是像 (hsql/call :my_function 1 2) 這樣的表單。(hsql/raw "x") 現在是 [:raw "x"]。可以使用 honey.sql/register-fn! 向 Honey SQL 2 註冊新的處理常式。沒有 Honey SQL 1 honeysql.format./ToSql 通訊協定的等效項目，因此您不應再定義一次性類型來實作自訂 SQL 編譯規則。請改用 honey.sql/register-fn!。

  4. 在 Honey SQL 1 中，您可以透過實作多重方法 honeysql.format/fn-handler，在更有限的程度上註冊函數。Metabase 以這種方式註冊了函數 :extract、:distinct-count 和 :percentile-cont。對於 Honey SQL 2，我們已將這些函數註冊為 metabase.util.honey-sql-2 命名空間中的限定關鍵字，以防止混淆它們的定義位置。因此，如果您使用這些函數，則需要更新關鍵字。

    ;;; Honey SQL 1
(hsql/call :distinct-count expr)

    變為

    ;;; Honey SQL 2
(require '[metabase.util.honey-sql-2 :as h2x])

[::h2x/distinct-count expr]

  5. 由於自訂運算式現在只是像 [:my_function 1] 這樣的純向量，因此如果運算式出現在 :select、:from 或其他向量可能被解譯為 [expression alias] 的位置，您可能需要將運算式包裝在額外的向量中。例如

    ;; Honey SQL 1
(honeysql.core/format {:select [[:my_function 1]]})
;; => ["SELECT my_function AS 1"]

;; Honey SQL 2
;;
;; WRONG
(honey.sql/format {:select [[:my_function 1]]})
;; => ["SELECT my_function AS ?" 1]

;; CORRECT
(honey.sql/format {:select [[[:my_function 1]]]})
;; => ["SELECT MY_FUNCTION(?)" 1]

    SQL 查詢處理器會自動為其產生的表單執行此操作，因此您只需擔心是否覆寫其產生 :select 或其他最上層子句的方式。

  6. 數字預設為參數化，例如 {:select [1]} 變成 SELECT ? 而不是 SELECT 1。您可以使用 :inline 強制內嵌產生 SQL：{:select [[[:inline 1]]]} 變成 SELECT 1。由 SQL 查詢處理器程式碼產生的數字應自動內嵌，但您可能需要確保您產生的任何數字都包裝在 :inline 中，如果它們最終可能成為 GROUP BY 子句內的運算式。有些資料庫只有在未參數化時才能辨識運算式是否為相同的東西

    -- This is okay
SELECT x + 1
FROM table
GROUP BY x + 1

-- Bad: DB doesn't know whether the two x + ? expressions are the same thing
SELECT x + ?
FROM table
GROUP BY x + ?

使用 :inline 內嵌內容時請謹慎 - 請注意不要在不受信任的字串或其他 SQL 注入管道上使用它。僅內嵌 number? 的內容是安全的。

如需有關程式庫版本之間差異的更多資訊，請閱讀 Honey SQL 1.x 和 2.x 之間的差異。

注意：希望這些重大變更會在 0.46.0 發佈之前修正。如果已修正，將會更新此內容。

類別 metabase.util.honeysql_extensions.Identifer 和 metabase.util.honeysql_extensions.TypedHoneySQLForm 已分別移至 metabase.util.honey_sql_1.Identifer 和 metabase.util.honey_sql_1.TypedHoneySQLForm。如果您驅動程式直接參考這些類別名稱，則可能需要更新內容以使用新的類別名稱。

同樣地，已移除 metabase.util.honeysql-extensions/->AtTimeZone；請改用 metabase.util.honeysql-extensions/at-time-zone。

Metabase 0.45.0

  • metabase.driver.sql-jdbc.connection/details->connection-spec-for-testing-connection 已在 Metabase 0.45.0 中移除，因為它洩漏了 SSH 通道。請參閱 #24445。如果您正在使用此函數，請更新您的程式碼以改用 metabase.driver.sql-jdbc.connection/with-connection-spec-for-testing-connection，它會在之後正確清除。

新方法

  • 已新增 metabase.driver.sql-jdbc.sync.describe-table-fields。如果您想要覆寫擷取表格欄位中繼資料（例如類型）的預設行為，請實作此方法。

  • 已新增 metabase.driver.sql-jdbc.sync.describe-table/get-table-pks。此方法用於取得給定表格的 pk 集合。

  • 已新增 ->honeysql [<driver> :convert-timezone]。如果您希望您的驅動程式支援 convertTimezone 運算式，請實作此方法。此方法採用 2 個或 3 個引數，並傳回 timestamp without time zone 資料行。

Metabase 0.43.0

  • MBQL 查詢中的 :expressions 映射現在使用字串作為鍵，而不是關鍵字 (請參閱 #14647)。如果您直接存取或操作此映射，則只需注意這一點。衍生自 :sql 並實作 ->honeysql 以用於 [<driver> :expression] 的驅動程式可能需要更新。自 Metabase 0.35.0 以來，已提供實用工具函數 metabase.mbql.util/expression-with-name，並且可以處理這兩種鍵類型。強烈建議您使用此函數，而不是直接存取 :expressions，因為這樣做可以使您的驅動程式與 0.42.0 以及 0.43.0 和更新版本相容。

  • 現在在 sql-jdbc.sync 命名空間下有一個 describe-nested-field-columns 方法，它會傳回 NestedFCMetadata 的實例。這是為了允許 Postgres 中的 JSON 欄位，以及最終允許其他通常是普通 RDBMS 的資料庫，但有時它們會有一個包含 JSON 或其他語意的反正規化欄位。給定一個具有反正規化欄位的表格，這些欄位具有巢狀欄位語意 (因此，類型化的子欄位仍然是反正規化的，但在列之間類型穩定)，傳回值應該是 NestedFCMetadata，它是扁平化鍵路徑到偵測到的子欄位的映射。同步中的欄位偵測將會透過這些巢狀類型來豐富。這與我們對 mongo 所做的方式有本質上的不同，因為每種 JSON 欄位都不同，但它將在每次同步時執行，所以即使在巨大的表格和這些巨大表格上的巨大反正規化欄位上，它也不能太慢。

Metabase 0.42.0

Metabase 0.42.0 中的變更會影響衍生自 :sql (包括 :sql-jdbc) 的驅動程式。非 SQL 驅動程式可能不需要任何變更。

0.42.0 為 SQL 查詢處理器編譯和決定 MBQL :field 子句別名的方式引入了幾項重大變更。如需更多背景資訊，請參閱提取請求 #19384。

如果您正在操作欄位或表格別名，我們整合了許多重疊的變數和方法，這表示您可能需要刪除已棄用的方法實作。

重大變更

  • 用於欄位實例的 metabase.driver.sql.query-processor/->honeysql 方法，例如

    (defmethod sql.qp/->honeysql [:my-driver (class Field)]
  [driver field]
  ...)

    不再調用。所有編譯現在都由 MBQL :field 子句方法處理，例如

    (defmethod sql.qp/->honeysql [:my-driver :field]
  [driver field-clause]
  ...)

    如果您在此處執行了某些特殊操作，則需要將該特殊邏輯移至 [<driver> :field] 中。(但是，您可能不再需要此特殊邏輯 - 請參閱下文。)

  • :field、:expression 和 :aggregation-options 子句現在包含有關您應該使用哪些別名來在 SQL AS 的左側和右側或查詢中的其他位置引用它們的資訊。請參閱 PR #19610 以取得有關新資訊的詳細討論，以下稱為 /#19610 資訊/。

  • 如果您有 ->honeysql 的自訂實作，用於 :field 或 (class Field)：用於 :field 的 ->honeysql 方法應該使用或替換 #19610 資訊，而不是嘗試以其他方式決定或覆寫它。

新方法

  • metabase.driver/escape-alias (從 0.41.0 中引入的 metabase.driver.sql.query-processor/escape-alias 移動而來) 現在用於產生 #19610 資訊，並在整個 SQL QP 程式碼中一致地使用。如果您需要基於任何原因轉換產生的欄位別名 (例如，逸出不允許的字元)，請實作此方法。

  • 已新增 metabase.driver.sql-jdbc.sync.interface/filtered-syncable-schemas，最終將取代 metabase.driver.sql-jdbc.sync.interface/syncable-schemas。它的用途類似，不同之處在於它還傳遞了包含和排除模式 (例如：auth*,data*) 以進一步篩選將同步的結構描述。

已棄用的方法和變數

除非另有說明，否則以下方法和變數預計將在 Metabase 0.45.0 中移除。

  • metabase.driver/format-custom-field-name 現在未使用。請改為實作 metabase.driver/escape-alias。

  • metabase.driver.sql.query-processor/escape-alias 已重新命名為 metabase.driver/escape-alias。其他一切都相同。

  • metabase.driver.sql.query-processor/field-clause->alias 不再使用選用參數 unique-name-fn。別名現在會在逸出後自動變得唯一；如果您需要在它們變得唯一之前執行某些特殊操作，請實作 metabase.driver/escape-alias。(如果您需要執行 /真正/ 特殊的操作，唯一別名也會再次逸出。)

  • 在 0.41.0 中已棄用的 metabase.driver.sql.query-processor/field->alias 在 0.42.0 中現在未使用。實作此方法不再有任何效果。如果您需要執行某些特殊操作，請改為實作 metabase.driver/escape-alias；如果您需要基於某種原因逸出別名，請使用 #19610 資訊。此方法仍預計在 Metabase 0.44.0 中移除。

  • metabase.driver.sql.query-processor/*field-options* 現在未使用，且不再自動繫結。如果您基於某些原因需要欄位選項，請參閱我們的 SQL Server 驅動程式，以取得如何建立它的範例。

  • metabase.driver.sql.query-processor/*table-alias* 現在未使用，且不再自動繫結。請改為使用或覆寫來自 #19610 資訊 的 :metabase.query-processor.util.add-alias-info/source-table。

  • metabase.driver.sql.query-processor/*source-query* 現在未使用，且不再自動繫結。請改為使用 metabase.driver.sql.query-processor/*inner-query*，它始終繫結，即使我們不在來源查詢內部。

  • metabase.driver.sql.query-processor/field->identifier 現在未使用。在任何情況下都不應再需要實作此方法。如果您需要在此處執行某些特殊操作，請覆寫用於 [<driver> :field] 的 ->honeysql 並操作 #19610 資訊。

  • metabase.driver.sql.query-processor/prefix-field-alias 不再使用。先前，它被提供用於讓驅動程式有機會逸出自動產生的聯結欄位別名。這不再必要，因為 metabase.driver/escape-alias 會在自動產生的別名上呼叫。如果您需要執行某些特殊操作，請實作 metabase.driver/escape-alias。
  • metabase.driver.sql-jdbc.sync.interface/syncable-schemas 已棄用，改為使用 metabase.driver.sql-jdbc.sync.interface/filtered-syncable-schemas (請參閱上文)。現有的 syncable-schemas 預設實作目前呼叫 filtered-syncable-schemas (使用 nil 篩選器，即篩選操作實際上是無操作)，但它最終將被移除。

已移除的方法和變數

  • 在 0.39.0 中已棄用的 metabase.mbql.schema/DatetimeFieldUnit 現在已移除。

舊版本

在 0.42.0 之前，此資訊在我們的 Wiki 中追蹤。您可以在下表中找到 0.42.0 之前版本的變更

版本 Wiki 頁面
0.41.0 變更
0.40.0 無變更。
0.39.0 無變更。
0.38.0 變更
0.37.0 變更
0.36.0 變更
0.35.0 變更

閱讀其他 Metabase 版本 的文件。