定价
登录 开始使用
文档 学习
主页
分析
嵌入
管理
其他资源

驱动程序接口更新日志

Metabase 0.55.0

  • 添加多方法 ->date，允许驱动程序控制如何将字符串和时间类型转换为日期。

  • 添加多方法 date-dbtype，允许驱动程序控制日期转换成的类型。

  • 扩展 date() 以接受 DateTime（或等效的 DB 类型）以及 ISO 字符串。当给定 DateTime 时，它将截断为日期。

  • 为支持将 iso 字符串转换为 datetimes 的驱动程序添加了功能 :expressions/datetime

  • 为支持由单个字符串、数字或布尔文字值组成的表达式的驱动程序添加了功能 :expression-literals。

  • 为支持数据库和模式之间分层级别的驱动程序添加了功能 :multi-level-schema。例如 databricks 的目录。默认为 false。

  • 添加了多方法 adjust-schema-qualification，允许驱动程序根据启用或禁用多级模式支持来限定或取消限定表模式。驱动程序可能需要实现 sql.qp/->honeysql [driver ::h2x/identifier] 来正确引用完全限定的模式。

  • 添加了多方法 float-dbtype，它返回我们用于强制转换策略和 float() 自定义表达式函数的浮点类型名称。

  • 为支持将文本强制转换为浮点数的驱动程序添加了功能 :expressions/float。

  • 添加了多方法 integer-dbtype，允许驱动程序控制整数强制转换成的类型。

  • metabase.upload 命名空间已替换为 metabase.upload.core，但上传类型关键字（例如 :metabase.upload/varchar-255）保持不变。确保您没有在 metabase.driver/upload-type->database-type 或 metabase.driver/allowed-promotions 等方法中使用 :: 关键字 – 确保您使用 :metabase.upload/varchar-255 而不是类似 ::upload/varchar-255 的内容。

  • metabase.models.secret 命名空间已替换为 metabase.secrets.core；如果您正在使用它，请更新您的用法。

  • 命名空间 metabase.public-settings 已被移除，设置已移动到适当的模块，例如 site-uuid 现在位于 metabase.system.core 中。如果您正在使用此命名空间，请相应地更新您的代码。您可以通过查看这些设置在我们第一方驱动程序中的使用方式来找到正确的命名空间。

  • 命名空间 metabase.models.field、metabase.models.field-values 和 metabase.models.table 已分别移动到 metabase.warehouse-schema.field、metabase.warehouse-schema.field-values 和 metabase.warehouse-schema.table。您不应该直接在您的驱动程序中使用这些命名空间，但如果您使用了，请更新您的引用。

  • metabase.driver.sql.query-processor/->honeysql 不再支持 :model/Table（对此的支持在 0.48.0 中已弃用）——此方法将不再使用；如果您有此类方法，请将其迁移到 :metadata/table。如果您有 :model/Table 并且需要 :metadata/table（例如在 metabase.driver/table-rows-seq 的实现中），您可以使用 metabase.lib.metadata/table。

  • metabase.db.metadata-queries 已被移除；供驱动程序使用的部分已移至 metabase.driver.common.table-rows-sample。

  • metabase.util.ssh 已移至 metabase.driver.sql-jdbc.connection.ssh-tunnel。

  • metabase.query-processor.pipeline/*query-timeout-ms* 已移至 metabase.driver.settings/*query-timeout-ms*。

  • 命名空间 metabase.query-processor.context（在 0.50.0 中已弃用）已被移除。

  • 以前在 metabase.driver.* 命名空间中的所有设置已移至 metabase.driver.settings，并且以前在 metabase.query-processor.* 命名空间中的所有设置已移至 metabase.query-processor.settings。

Metabase 0.54.11

  • 多方法 metabase.driver.sql-jdbc.sync.interface/active-tables 和 metabase.driver.sql-jdbc.sync.interface/filtered-syncable-schemas，以及函数 metabase.driver.sql-jdbc.sync.describe_database/fast-active-tables、metabase.driver.sql-jdbc.sync.describe_database/have-select-privilege-fn 和 metabase.driver.sql-jdbc.sync.describe_database/db-tables 现在接受数据库规范而不是 java.sql.Connection 对象。

Metabase 0.54.10

  • 添加 metabase.driver/table-known-to-not-exist? 以供驱动程序测试异常是否是由于对不再存在的表进行查询而导致的
  • 为 JDBC 驱动程序添加 metabase.driver.sql-jdbc/impl-table-known-to-not-exist?。这是 table-known-to-not-exist 对 JDBC 的实现，允许直接针对 java.sql.SQLException 抛出的异常进行测试，而无需担心异常原因链。

Metabase 0.54.0

  • 添加了多方法 allowed-promotions，允许驱动程序控制上传支持哪些列类型提升。

  • 添加了多方法 alter-table-columns!，类似于 alter-columns! 但接受额外的关键字参数选项。现有的 alter-columns! 实现将默认使用。

  • alter-columns! 现在被标记为已弃用。驱动程序应寻求实现新的 alter-table-columns! 方法。

  • 多方法 metabase.driver.sql-jdbc.sync.interface/alter-table-columns-sql 已添加，类似于 alter-columns-sql 但接受额外的关键字参数选项。现有的 alter-columns-sql 实现将默认使用。

  • metabase.driver.sql-jdbc.sync.interface/alter-columns-sql 现在被标记为已弃用。驱动程序应寻求实现新的 alter-table-columns-sql 方法。

  • 添加了功能 :test/arrays 和多方法 native-array-query，以支持对支持数组类型的数据库进行数组类型测试。

  • 为支持强制转换为文本的驱动程序添加了功能 :expressions/text

  • 为支持将文本强制转换为日期的驱动程序添加了功能 :expressions/date

  • 为支持将文本强制转换为整数的驱动程序添加了功能 :expressions/integer

  • 为支持 distinct-where 函数的驱动程序添加了功能 :distinct-where。

  • 为支持 split-part 函数的驱动程序添加了功能 :split-part。

Metabase 0.53.12

  • 为驱动程序添加 metabase.driver/query-canceled?，以测试异常是否是由于用户操作取消查询所致
  • 为 JDBC 驱动程序添加 metabase.driver.sql-jdbc/impl-query-canceled?。这是 JDBC 中 query-canceled 的实现，允许直接针对 java.sql.SQLException 抛出的异常进行测试，而无需担心异常原因链。

Metabase 0.53.10

  • 为 JDBC 驱动程序添加了 metabase.driver.sql-jdbc.sync/describe-fields-pre-process-xf。这允许在不重新实现 driver/describe-fields 的情况下操作 metabase.driver.sql-jdbc.sync/describe-fields-sql 的结果。

Metabase 0.53.0

  • 添加了多方法 bad-connection-details 以允许为测试模拟错误的连接参数。

  • 添加了 driver/dynamic-database-types-lookup 及其 :postgres 实现。该方法生成一个 database_type 到 base_type 的映射，用于动态类型，即那些不属于 sql-jdbc.sync/database-type->base-type 覆盖的类型。其最初目的是为了在 postgres 中启用用户定义枚举到结果元数据中适当基本类型的映射。

Metabase 0.52.12

  • 添加了多方法 metabase.driver/db-details-to-test-and-migrate。这可用于清理和迁移以前版本中模糊的连接详细信息。

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，并使用驱动程序方法 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 字符串并将其去参数化或“unprepare”）已被移除。相反，如果您需要一个直接将参数拼接进 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。它可用于实现每个批次的特殊行为，例如在 metabase.test.data.sql-jdbc.load-data/do-insert! 方法中将批次写入 CSV 文件以单独加载。请参阅 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 上下文；适当的连接类型会在调用代码中自动创建并传入。请相应地更新您的方法实现和用法。

  • 添加了方法 metabase.test.data.interface/dataset-already-loaded? 来检查测试数据集是否已加载。基于 JDBC 的驱动程序有一个默认实现，用于检查我们是否可以连接到数据库；对于在测试中不实际物理创建新数据库的驱动程序，您可能需要覆盖此方法。您可以通过运行测试 metabase.test.data.sql-jdbc-test/dataset-already-loaded?-test 来检查您的基于 JDBC 的驱动程序是否使用默认实现正确工作。

  • 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，则现在将执行重映射和隐式连接的测试。

  • 添加了 :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，但对于少数驱动程序（如旧的、非 JDBC Druid 驱动程序）来说，它却是必需的，以便找到所有时间字段引用并为它们加上 :temporal-unit :default。此默认设置以前应用于所有驱动程序，但它引入了一些下游问题，因此现在只有需要它的驱动程序才能设置此功能。

Metabase 0.50.17

  • 添加了方法 metabase.driver/incorporate-auth-provider-details，用于合并身份验证提供程序响应到数据库详细信息所需的特定于驱动程序的行为。在大多数情况下，这意味着根据身份验证提供程序及其响应设置 :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。请参阅 metabase.driver.sql.query-processor/preprocess 的默认 :sql 实现，了解在需要时使用此转换的示例。

    您可以运行 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 中 :druid-jdbc 的 sql-jdbc.sync/database-type->base-type 实现以及 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 类型。默认值为 false。

Metabase 0.49.22

  • 新增了一个可选方法 metabase.driver.sql/json-field-length。所有派生自 :sql 并支持 :nested-field-columns 功能的驱动程序都应实现此方法。如果实现，Metabase 将在“sync-fields”步骤中跳过查询大型 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.driver.sql.query-processor/->honeysql 的 SQL 驱动程序，对于 metabase.models.table/Table/:model/Table，应更新为针对 :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 返回的 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 键的 Field 元数据，而前者传递了带有 snake_case 键的传统元数据。

  • metabase.driver/current-db-time（在 0.34 中弃用）以及相关方法和辅助函数已被移除。请改实现 metabase.driver/db-default-timezone。

  • metabase.driver.sql-jdbc.sync.interface/db-default-timezone，一个用于为基于 JDBC 的驱动程序编写 metabase.driver/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\"}"

    请参阅我们的 示例数独驱动程序构建说明，了解该命令的解释。

    请注意，虽然此命令本身输入起来很长，但您不再需要在驱动程序的 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，因为它不遵守 limit 子句。

  • 已添加多方法 metabase.driver.sql.query-processor/datetime-diff。此方法由 :datetime-diff 子句的 ->honeysql 实现使用。如果您希望对 :datetime-diff 使用 ->honeysql 的默认 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 不再存在；不再使用 (hsql/call :my_function 1 2) 这样的形式，您只需返回一个普通向量，如 [:my_function 1 2]。(hsql/raw "x") 现在是 [:raw "x"]。可以使用 Honey SQL 2 的 honey.sql/register-fn! 注册新的处理程序。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。此方法用于获取给定表的主键集。

  • 已添加 ->honeysql [<driver> :convert-timezone]。如果您希望驱动程序支持 convertTimezone 表达式，请实现此方法。此方法接受 2 或 3 个参数，并返回一个 timestamp without time zone 列。

Metabase 0.43.0

  • MBQL 查询中的 :expressions 映射现在使用字符串作为键而不是关键字（请参阅 #14647）。您只需在直接访问或操作此映射时才需要关注此问题。派生自 :sql 并为 [<driver> :expression] 实现 ->honeysql 的驱动程序可能需要更新。一个实用函数 metabase.mbql.util/expression-with-name 自 Metabase 0.35.0 以来一直可用，并处理两种类型的键。强烈建议您使用此函数，而不是直接访问 :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。

如果您正在操作字段或表别名，我们整合了许多重叠的变量和方法，这意味着您可能需要删除已弃用的方法实现。

重大变更

  • Field 实例的 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 信息/。

  • 如果您对 :field 或 (class Field) 有自定义的 ->honeysql 实现：->honeysql 对于 :field 的方法应使用或替换 #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。（如果您需要进行/非常/特殊的处理，唯一的别名还会被再次转义。）

  • metabase.driver.sql.query-processor/field->alias（在 0.41.0 中已弃用）在 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 现已不再使用。在任何情况下都不再需要实现此方法。如果需要进行特殊处理，请覆盖 ->honeysql 的 [<driver> :field]，并操作 #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 版本的文档。

© . All rights reserved.