Syncing and scanning databases

Metabase periodically runs different types of queries against your database to stay up to date with your schema and data. These automated processes help Metabase provide better suggestions, populate filter dropdowns, and automatically choose appropriate visualizations.

Overview of sync processes

Metabase performs three types of operations to understand your data:

Sync

Updates database schema, table structures, and field information

Scan

Samples column values for filter dropdowns and data type detection

Fingerprint

Computes statistics to improve visualizations and suggestions

Metabase doesn’t store complete tables from your database—only metadata, sample values, and statistics to improve the user experience.

Initial sync, scan, and fingerprinting

When you first connect a database to Metabase, it performs an initial sync to:

Discover all tables and views in your database
Identify columns and their data types
Detect relationships (foreign keys)
Automatically assign semantic types
Sample field values for filters
Compute statistics for better visualizations

Monitoring sync progress

You can track the progress of these operations:

Click the grid icon in the top right
Go to Admin > Tools > Tasks
Filter by sync-related tasks

What data is collected during initial sync?

Sync collects:

Table and view names
Column names and data types
Primary and foreign key relationships

Scan samples:

First 1,000 distinct values per column (for filters)
Up to 100 KB of text per column

Fingerprinting analyzes:

First 10,000 rows of each table
Computes min/max, averages, null ratios
Detects special types (URLs, emails, geographic data)

Viewing and editing synced metadata

Once the initial sync completes, you can view and customize the metadata:

Go to Admin > Table Metadata
Select your database and table
Edit field types, visibility, and other settings

For more information, see Editing metadata.

How database syncs work

A sync is a lightweight query that updates Metabase’s understanding of your database schema.

What it does
SQL query
Performance

Data collected during sync

What collected	Why it’s needed
Table names	Display tables in query builder
Field names	Show available columns
Field data types	Proper querying and type handling
Primary keys	Enable detailed views and table display
Foreign keys	Auto-join tables and visualize relationships

The sync query

Metabase runs a query like this against each table:

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

This query returns no data—only metadata about the table structure.

How database scans work

A scan is a more intensive query that samples column values to populate filter dropdowns and improve the user experience.

What it does
SQL query
Limits & caching

Data collected during scan

What collected	Why it’s needed
Distinct category values	Populate filter dropdown menus
Active field values	Improve filter UI performance
Advanced field values	Support row and column security

Scans only include “active fields”—fields used within the past 14 days. Inactive fields become active again when someone uses them.

The scan query

Metabase runs queries like this for each column:

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

This retrieves the first 1,000 distinct values in ascending order.

How database fingerprinting works

Metabase fingerprints your data by sampling rows and computing statistics to provide better suggestions and visualizations.

What it does
SQL query
When it runs

Data collected during fingerprinting

What collected	Why it’s needed
Distinct value count	Determine field caching strategy
Min/max numeric values	Enable binning and range filters
Date ranges	Set date filter defaults
Special type detection	Identify URLs, emails, geographic data
Null value ratio	Assess data quality
Average/median values	Set visualization defaults
Text length metrics	Hide overly long text fields

The fingerprinting query

Metabase runs queries like this:

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

This samples the first 10,000 rows to compute statistics.

Choose when syncs and scans happen

By default, Metabase performs:

Hourly syncs: Lightweight schema updates
Daily scans: Intensive field value sampling

For large databases, you may want to control when these operations occur.

Configuring sync and scan schedules

Click the grid icon in the top right
Go to Admin > Databases
Select your database
Click Edit connection details in the “Connection and sync” section
Expand Show advanced options
Toggle Choose when syncs and scans happen

Database syncing
Scanning for filter values

Sync schedule options

Configure when schema syncs occur:

Frequency: Hourly (default) or daily
Time: Specific time to run (in server timezone)

The time is based on the timezone where your Metabase server is running.

Manual sync and scan operations

Manually syncing tables and columns

To immediately update your database schema:

Go to Admin > Databases
Select your database
Click Sync database schema now

This is useful after making schema changes to your database, like adding new tables or columns.

Manually scanning column values

Scan entire table
Scan specific column

To scan all columns in a table:

Go to Admin > Table Metadata
Select your database and table
Click the gear icon at the top of the page
Click Re-scan this table

Clearing cached values

Clear table cache
Clear field cache

To clear all cached field values for a table:

Go to Admin > Table Metadata
Select your database and table
Click the gear icon in the upper right
Click Discard cached field values

Periodically refingerprint tables

Enabling periodic refingerprinting will increase the load on your database, as Metabase will sample 10,000 rows from each table during every sync.

By default, Metabase only fingerprints your data once during initial setup. If your data patterns change significantly over time, you may want to enable periodic refingerprinting:

Go to Admin > Databases
Select your database
Click Edit connection details
Expand Show advanced options
Turn on Periodically refingerprint tables

This will run fingerprinting queries during each sync to keep statistics current.

Disabling syncing and scanning for specific tables

To prevent Metabase from syncing and scanning a specific table, hide it:

Go to Admin > Table Metadata
Select your database
Hover over the table name in the sidebar
Click the eye icon to hide the table

Hidden tables won’t appear in the query builder or data reference. However, users can still query hidden tables using the SQL editor.

Syncing and scanning using the API

You can trigger syncs and scans programmatically using the Metabase API.

Authenticated endpoints
Notify endpoints

Sync or scan with user authentication

These endpoints require authentication with a user ID and session token:

# Sync database schema
POST /api/database/{id}/sync_schema

# Re-scan field values
POST /api/database/{id}/rescan_values

Notify endpoints for ETL workflows

Use these endpoints with an API key for automated syncing after ETL operations:

# Sync entire database or specific table
POST /api/notify/db/{id}

# Sync only a new table
POST /api/notify/db/{id}/new-table
# Requires: schema_name and table_name parameters

These endpoints require the MB_API_KEY environment variable (distinct from Metabase’s user API keys).

Example: Sync after ETL job

You can call the sync API at the end of your ETL pipeline to ensure Metabase has the latest schema:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ${MB_API_KEY}" \
  https://your-metabase.com/api/notify/db/1

For complete API documentation, see API reference.

Understanding sync, scan, and fingerprint impact

Database load
Best practices
Monitoring

Impact on your database

Operation	Frequency	Load	Duration
Sync	Hourly (default)	Minimal	Seconds
Scan	Daily (default)	Moderate	Minutes
Fingerprint	Once (default)	Higher	Minutes to hours

Actual impact depends on your database size, number of tables, and database performance.

Troubleshooting sync and scan issues

Tables or columns are missing

Possible causes:

Initial sync hasn’t completed
Tables are hidden
Database user lacks permissions
Schema not included in sync settings

Solutions:

Wait for initial sync to complete
Check table visibility in Table Metadata
Verify database user has SELECT privileges
Check schema inclusion in database settings
Manually trigger a sync

See: Can’t see tables

Filter dropdowns are empty or outdated

Possible causes:

Field hasn’t been scanned yet
Cache is outdated
Field hasn’t been used in 14+ days (inactive)
Scan is disabled

Solutions:

Manually re-scan the field
Clear and refresh the field cache
Use the field in a question to make it active
Enable scheduled scans

Data doesn't match database

Possible causes:

Cached values are stale
Sync hasn’t run since schema changes
Query results are cached

Solutions:

Manually sync the database
Clear cached field values
Refresh the question (not just cached results)
Check sync schedule and adjust if needed

See: Data doesn’t match database

Sync or scan is failing

Possible causes:

Database connection issues
Insufficient database permissions
Database server timeout
Large tables causing timeouts

Solutions:

Check database connection status
Verify database user permissions
Review database server logs
Hide very large tables that aren’t needed
Increase database timeout settings if needed

Can't see tables

Troubleshoot missing tables and columns

Sync troubleshooting

Fix sync and fingerprinting issues

Metadata editing

Customize table and field metadata

Semantic types

Understand how Metabase categorizes fields

Getting Started

Questions & Dashboards

Data Modeling

Database Connections

Embedding

Administration

Installation & Operations

AI Features

​Syncing and scanning databases

​Overview of sync processes

Sync

Scan

Fingerprint

​Initial sync, scan, and fingerprinting

​Monitoring sync progress

​Viewing and editing synced metadata

​How database syncs work

​Data collected during sync

​The sync query

​Sync performance

​How database scans work

​Data collected during scan

​The scan query

​Scan limits

​When cached values are used

​How database fingerprinting works

​Data collected during fingerprinting

​The fingerprinting query

​Fingerprinting schedule

​Choose when syncs and scans happen

​Configuring sync and scan schedules

​Sync schedule options

​Scan schedule options

​Manual sync and scan operations

​Manually syncing tables and columns

​Manually scanning column values

​Clearing cached values

​Periodically refingerprint tables

​Disabling syncing and scanning for specific tables

​Syncing and scanning using the API

​Sync or scan with user authentication

​Notify endpoints for ETL workflows

​Example: Sync after ETL job

​Understanding sync, scan, and fingerprint impact

​Impact on your database

​Optimization tips

​Monitor sync performance

​Troubleshooting sync and scan issues

​Further reading

Can't see tables

Sync troubleshooting

Metadata editing

Semantic types

Build docs developers (and LLMs) love

Syncing and scanning databases

Overview of sync processes

Initial sync, scan, and fingerprinting

Monitoring sync progress

Viewing and editing synced metadata

How database syncs work

Data collected during sync

The sync query

Sync performance

How database scans work

Data collected during scan

The scan query

Scan limits

When cached values are used

How database fingerprinting works

Data collected during fingerprinting

The fingerprinting query

Fingerprinting schedule

Choose when syncs and scans happen

Configuring sync and scan schedules

Sync schedule options

Scan schedule options

Manual sync and scan operations

Manually syncing tables and columns

Manually scanning column values

Clearing cached values

Periodically refingerprint tables

Disabling syncing and scanning for specific tables

Syncing and scanning using the API

Sync or scan with user authentication

Notify endpoints for ETL workflows

Example: Sync after ETL job

Understanding sync, scan, and fingerprint impact

Impact on your database

Optimization tips

Monitor sync performance

Troubleshooting sync and scan issues

Further reading