同步和扫描数据库

Metabase 会定期在您的数据仓库中运行不同类型的查询，以保持您的数据库元数据最新。了解有关您数据的信息有助于 Metabase 完成诸如自动显示正确图表、填充筛选器控件的下拉菜单等操作。

• 同步数据库架构：获取数据库架构、表结构、字段、约束（主键和外键）以及禁用已删除的表。
• 扫描字段值：对列值进行抽样，以填充筛选器下拉菜单、查找不重复值并识别有效的可视化。Metabase 不会存储您数据库的完整表。
• 指纹识别：对表的前 10,000 行进行抽样，以根据每个字段的类型计算统计信息，特别是：不重复值计数、空值百分比（所有字段类型）、平均值、中位数、最小值、最大值和四分位数（数值类型）。

初始同步、扫描和指纹识别

当 Metabase 首次连接到您的数据库时，它会执行同步以确定表中列的元数据，并自动为每个列分配一个语义类型。

您可以从齿轮图标 >管理设置 > 工具 > 任务中跟踪这些查询的进度，并按各种同步任务进行筛选。

查询运行完成后，您可以在管理设置 > 表元数据中查看和编辑同步的元数据。有关更多信息，请参阅编辑元数据。

选择同步和扫描发生的时间

默认情况下，Metabase 会执行轻量级的每小时同步和每日集中的字段值扫描。如果您有一个大型数据库，您可能需要选择同步和扫描发生的时间。

1. 点击齿轮图标。
2. 选择管理员设置。
3. 转到数据库。
4. 选择您的数据库。
5. 在连接和同步部分，点击编辑连接详细信息。
6. 展开显示高级选项。
7. 切换选择同步和扫描发生的时间。

在那里，您可以设置同步和扫描的计划。

数据库同步

选项包括

• 同步的频率：每小时（默认）或每天。
• 同步运行的时间，以 Metabase 应用程序运行的服务器的时区为准。

扫描筛选值

扫描将仅包括“活动字段”：在过去十四天内使用过的字段。Metabase 不会扫描超过十四天未使用的字段。已非活动状态的字段将在有人使用时再次激活，Metabase 将在下次扫描中包含它们。

选项包括

• 定期、按计划允许您以与数据库更改速率相匹配的频率运行扫描查询。时间以运行 Metabase 应用程序的服务器的时区为准。对于小型数据库或不重复值经常更新的表，这是最佳选择。
• 仅在添加新筛选器控件时是如果您希望扫描查询按需运行时的一个好选项。将此选项打开意味着 Metabase 只会扫描和缓存当有人向仪表板或 SQL 问题添加新筛选器控件时使用的字段值的缓存（即，他们向 SQL 查询添加参数）。
• 从不，如果需要，我会手动执行是适用于数据库的选项，这些数据库要么过大，要么从不添加新值。使用重新扫描字段值按钮来运行手动扫描并将筛选值更新到最新。

无论您选择哪个选项，如果您设置一个字段在筛选器控件中使用下拉列表，Metabase 都需要获取该下拉列表的值。每当有人使用该筛选器控件时，Metabase 会先查找缓存的值（有效期为十四天）来填充该下拉列表；否则，它将重新扫描该字段以获取最新的值。

手动同步表和列

1. 转到管理设置 > 数据库 > 您的数据库。
2. 点击同步数据库架构。

手动扫描列值

扫描表中所有列的值

1. 转到管理设置 > 表元数据 > 您的数据库。
2. 选择您想与数据库同步的表。
3. 点击页面顶部的齿轮图标。
4. 点击重新扫描此表。

扫描特定列的值

1. 转到管理设置 > 表元数据 > 您的数据库。
2. 选择表。
3. 找到您想与数据库同步的列。
4. 点击该列面板中的齿轮图标。
5. 点击重新扫描此字段。

清除表或字段的缓存值

清除表的已扫描字段值

1. 转到管理设置 > 表元数据。
2. 选择数据库和表。
3. 点击右上角的齿轮图标。
4. 点击丢弃缓存的字段值。

您还可以通过点击字段上的齿轮图标并选择丢弃缓存的字段值来让 Metabase 忘记单个字段的缓存值。

禁用特定表的同步和扫描

要阻止 Metabase 对特定表运行同步和扫描，请将表可见性更改为隐藏

1. 转到管理设置 > 表元数据 > 您的数据库。
2. 将鼠标悬停在侧边栏中的表名称上。
3. 点击眼睛图标。

隐藏一个表也会阻止它出现在查询生成器和数据参考中。用户仍然可以从SQL 编辑器查询隐藏的表。

使用 API 进行同步和扫描

Metabase 定期进行同步和扫描，但如果数据库管理员刚刚更改了数据库架构，或者大量数据在特定时间自动添加，您可能需要编写一个使用Metabase API 来强制进行同步或扫描的脚本。API 提供了两种方式来启动数据库的同步或扫描。

同步或扫描数据库

您可以通过用户 ID 进行身份验证并将会话令牌传递到请求的标头中来使用这些端点。

• 同步数据库架构：/api/database/{id}/sync_schema
• 重新扫描字段值：/api/database/{id}/rescan_values

同步单个表

• /api/notify/db/{id} 用于通知 Metabase 同步数据库，或者可选地同步特定表。
• /api/notify/db/{id}/new-table 用于同步新表，而无需同步整个数据库。需要schema_name和table_name。

要使用此端点，您必须通过MB_API_KEY环境变量传递一个字符串。此字符串与 Metabase 的API 密钥不同。

我们创建了notify端点，以便人们可以在 ETL 操作完成后通知 Metabase 进行同步。

请参阅我们的API 文档。

数据库同步工作原理

Metabase 的同步是一个查询，用于从您的数据库获取更新的表和视图名称、列名称以及列数据类型的列表。

SELECT
    TRUE
FROM
    "your_schema"."your_table_or_view"
WHERE
    1 <> 1
LIMIT 0

默认情况下，此查询在设置期间运行一次，然后每小时运行一次。对于大多数关系型数据库，此扫描查询运行速度很快，但对于 MongoDB 和某些社区构建的数据库驱动程序，则可能较慢。同步不能完全关闭，否则 Metabase 将无法工作。

以下是同步的数据类型及其原因

数据库扫描工作原理

Metabase 的扫描是一个查询，它通过查看每个表按升序排列的前 1,000 个不重复记录来缓存筛选器下拉菜单的列值。

SELECT
    "your_table_or_view"."column" AS "column"
FROM
    "your_schema"."your_table_or_view"
GROUP BY
    "your_table_or_view"."column"
ORDER BY
    "your_table_or_view"."column" ASC
LIMIT 1000

对于每条记录，Metabase 只存储前 100KB 的文本。因此，如果您有每条记录包含 1,000 个字符的数据（如地址），并且您的列有超过 100 个不重复地址，Metabase 将只缓存扫描查询的前 100 个值。

缓存的列值显示在筛选器下拉菜单中。如果用户在筛选器搜索框中输入的值不在前 1,000 个不重复记录或 100KB 文本中，Metabase 将在您的数据库上运行查询来动态查找这些值。

扫描比同步查询更耗费资源，因此它默认只在设置期间运行一次，然后每天运行一次。如果您完全禁用扫描，您需要通过运行手动扫描来更新。

为了减少 Metabase 需要扫描的表和字段数量以保持与连接数据库同步，Metabase 只会扫描过去十四天内有人使用的字段的值。

以下是扫描获取的数据类型及其原因

定期重新指纹识别表

定期重新指纹识别将增加数据库的负载。

默认情况下，Metabase 仅在您首次连接数据库时运行指纹识别查询。

如果您希望 Metabase 在 UI 中提供更好的建议时使用更大的列值样本，请打开此设置。

1. 转到管理 > 数据库 > 您的数据库。
2. 点击编辑连接详细信息。
3. 展开显示高级选项。
4. 打开定期重新指纹识别表。

数据库指纹识别工作原理

指纹识别查询会查看数据库中给定表或视图的前 10,000 行。

SELECT
    *
FROM
    "your_schema"."your_table_or_view"
LIMIT 10000

Metabase 使用此查询的结果在 Metabase UI 中提供更好的建议（例如自动分箱）。

为避免给您的数据库带来压力，Metabase 只在您第一次设置数据库连接时运行指纹识别查询。

默认情况下，Metabase 在第一次指纹识别后不会重新指纹识别您的数据库。要重新指纹识别您的数据，您可以打开定期重新指纹识别表。

以下是指纹识别获取的数据类型及其原因

延伸阅读

Metabase 在同步和扫描过程中不执行任何缓存或速率限制。如果您的数据似乎丢失或过时，请查看

• 看不到表.
• Metabase 中的数据与我的数据库不匹配.