Lance Data Viewer - A read-only web UI for Lance datasets

Browse Lance tables from your local machine in a simple web UI. No database to set up. Mount a folder and go.

Images are published for seven LanceDB versions, so you can pick the one that matches your data format.

Quick start (Docker)

1. Pull the recommended version

# Modern stable version (recommended for new projects)
docker pull ghcr.io/lance-format/lance-data-viewer:lancedb-0.33.0

2. Make your data readable (required)

# Make your Lance data directory and all contents readable by the container
chmod -R o+rx /path/to/your/lance

3. Run (mount your data)

docker run --rm -p 8080:8080 \
    -v /path/to/your/lance:/data:ro \
    ghcr.io/lance-format/lance-data-viewer:lancedb-0.33.0

4. Open the UI

http://localhost:8080

The UI will display the Lance version in the top-right corner for easy identification.

What counts as "Lance data" here?

A folder containing Lance tables (as created by Lance/LanceDB). The app lists tables under /data.

Available Lance Versions

Choose the container that matches your Lance data format:

Container Tag	Lance Version	PyArrow	Use Case
lancedb-0.33.0	0.33.0	>=16, <25	Recommended - Latest stable version
lancedb-0.29.2	0.29.2	>=16, <22	Modern stable version
lancedb-0.24.3	0.24.3	>=16, <22	Modern stable version
lancedb-0.16.0	0.16.0	16.1.0	Anchor stable for older datasets
lancedb-0.5	0.5.0	14.0.1	Legacy support
lancedb-0.3.4	0.3.4	14.0.1	Legacy support
lancedb-0.3.1	0.3.1	14.0.1	Legacy support

Viewing older Lance data

If you have datasets created with older Lance versions:

# For datasets created with Lance 0.16.x
docker run --rm -p 8080:8080 \
    -v /path/to/your/old/lance/data:/data:ro \
    ghcr.io/lance-format/lance-data-viewer:lancedb-0.16.0

# For very old datasets (Lance 0.3.x era)
docker run --rm -p 8080:8080 \
    -v /path/to/your/legacy/data:/data:ro \
    ghcr.io/lance-format/lance-data-viewer:lancedb-0.3.4

Tip: If you're unsure which version to use, start with lancedb-0.33.0 and if you get compatibility errors, try progressively older versions.

Features

• Read-only browsing with organized left sidebar (Datasets → Columns → Schema)
• Advanced vector visualization with CLIP embedding detection and sparkline charts
• Schema analysis with vector column highlighting and type detection
• Server-side pagination with inline controls and column filtering
• Robust error handling - gracefully handles corrupted datasets
• Responsive layout optimized for data viewing

Configuration (optional)

Variable	Default	Description
DATA_PATH	/data	Directory containing Lance tables
PORT	8080	Port the server listens on

• Port: change host port with -p 9000:8080, or set PORT env var to change the container's listening port.
• Read-only mount: keep :ro to avoid accidental writes in future versions.

Docker Compose

For pipelines or multi-container setups where lance-data-viewer shares a data volume with other services:

services:
  lance-viewer:
    image: ghcr.io/lance-format/lance-data-viewer:lancedb-0.33.0
    environment:
      DATA_PATH: /data
    volumes:
      - lance-data:/data:ro
    ports:
      - "8888:8080"

Port 8080 is the default inside the container. The example maps to 8888 on the host to avoid conflicts with services like Airflow or Jenkins that also use 8080.

Images & registries

All images are on the GitHub Container Registry: ghcr.io/lance-format/lance-data-viewer:TAG

Tag	Meaning
lancedb-{version}	Latest build for that Lance version (e.g. lancedb-0.33.0)
latest	Latest main-branch build of the recommended Lance version
stable	Most recent tagged release, recommended Lance version
v{app version}	Pin to an app release (e.g. v0.2.0)
app-{app version}_lancedb-{version}	Fully pinned: app release and Lance version

Build and test locally

# Build with specific Lance version (default: 0.33.0)
docker build -f docker/Dockerfile \
    --build-arg LANCEDB_VERSION=0.33.0 \
    -t lance-data-viewer:dev .

# Build multiple versions for testing
docker build -f docker/Dockerfile --build-arg LANCEDB_VERSION=0.24.3 -t lance-data-viewer:lancedb-0.24.3 .
docker build -f docker/Dockerfile --build-arg LANCEDB_VERSION=0.16.0 -t lance-data-viewer:lancedb-0.16.0 .
docker build -f docker/Dockerfile --build-arg LANCEDB_VERSION=0.3.4 -t lance-data-viewer:lancedb-0.3.4 .

# Make your Lance data readable (one-time setup)
chmod -R o+rx data

# Run with your data (replace 'data' with your lance folder path)
docker run --rm -p 8080:8080 -v $(pwd)/data:/data:ro lance-data-viewer:dev

# Open the web interface
open http://localhost:8080

# Test the API endpoints
curl http://localhost:8080/healthz
curl http://localhost:8080/datasets
curl "http://localhost:8080/datasets/your-dataset/rows?limit=5"

Run the test suite

The API tests run without Docker. With Python 3.11:

pip install -c backend/constraints-0.33.0.txt -r backend/requirements.txt
pip install pytest "httpx<0.28"
cd backend && python -m pytest tests/ -v

Swap the constraints file to test against a different Lance version. CI runs the suite against every supported version.

Development workflow

# Stop any running containers
docker ps -q | xargs docker stop

# Rebuild after code changes (with specific Lance version)
docker build -f docker/Dockerfile \
    --build-arg LANCEDB_VERSION=0.33.0 \
    -t lance-data-viewer:dev .

# Run in background
docker run --rm -d -p 8080:8080 -v $(pwd)/data:/data:ro lance-data-viewer:dev

# View logs
docker logs $(docker ps -q --filter ancestor=lance-data-viewer:dev)

# Check version info
curl http://localhost:8080/healthz | jq '.lancedb_version'

Supported Data Types

✅ Fully Supported

• Standard types: string, int, float, binary, timestamp, boolean, null
• Fixed-size vectors: fixed_size_list<item: float>[N] (e.g., CLIP-512), as written by Vector(dim) fields
• Variable-length vectors: list<item: float> and list<item: double>
• Structured data: nested structs and lists, including vectors inside them
• Indexed datasets: properly created with IVF/HNSW indexes

⚠️ Limited Support

• Corrupted data: the schema stays viewable and rows are replaced with an informative error message

❌ Not Supported

• Binary vectors (uint8 arrays), shown as plain lists without vector visualization
• Custom user-defined types
• Write operations (read-only viewer)

Vector Visualization Features

The viewer provides advanced visualization for vector embeddings:

• CLIP Detection: Automatically identifies 512-dimensional CLIP embeddings
• Statistics: Shows norm, sparsity, positive ratio, normalization status
• Sparkline Charts: Interactive visual representation of vector values
• Detailed Tooltips: Hover for comprehensive vector analysis
• Model Badges: Visual indicators for recognized embedding types

Security Notes

• Container runs as non-root
• No authentication; bind to localhost during development and run behind a reverse proxy if exposing
• Read-only access prevents accidental data modification

Contributing

See CONTRIBUTING.md for the design constraints and how to propose changes. Release history lives in CHANGELOG.md.