diff --git a/CHANGELOG.md b/CHANGELOG.md index 032e93b..e3fb502 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Frontend fetch calls now check `response.ok` before parsing JSON, so HTTP error responses surface as error states instead of being parsed as data (#27). - `/rows` with unknown column names and `/vector/preview` with a missing or non-vector column now return 400 as intended; the error was previously masked as a generic 500 (#28). +### Docs +- README refresh: corrected the supported-data-types section (variable-length float vectors render fully since #14; no 2048-dimension limit), documented the release image tags from #46, added test suite instructions, made 0.29.2 the recommendation throughout, and linked CONTRIBUTING.md and CHANGELOG.md (#51). + ## [0.2.0] - 2026-04-16 ### Added diff --git a/README.md b/README.md index fc28cf2..a7a5898 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ - - # 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. -**✨ Multi-Version Support**: Built for different Lance versions to ensure compatibility with your data format. +Images are published for six LanceDB versions, so you can pick the one that matches your data format. ![Lance Data Viewer Screenshot](lance_data_viewer_screenshot.png) @@ -50,7 +48,7 @@ Choose the container that matches your Lance data format: | Container Tag | Lance Version | PyArrow | Use Case | |--------------|---------------|---------|----------| -| `lancedb-0.29.2` | 0.29.2 | 21.0.0 | **Recommended** - Latest stable version | +| `lancedb-0.29.2` | 0.29.2 | >=16, <22 | **Recommended** - Latest stable version | | `lancedb-0.24.3` | 0.24.3 | 21.0.0 | 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 | @@ -73,7 +71,7 @@ docker run --rm -p 8080:8080 \ ghcr.io/lance-format/lance-data-viewer:lancedb-0.3.4 ``` -**Tip**: If you're unsure which version to use, start with `lancedb-0.24.3` and if you get compatibility errors, try progressively older versions. +**Tip**: If you're unsure which version to use, start with `lancedb-0.29.2` and if you get compatibility errors, try progressively older versions. ### Features @@ -101,7 +99,7 @@ For pipelines or multi-container setups where lance-data-viewer shares a data vo ```yaml services: lance-viewer: - image: ghcr.io/lance-format/lance-data-viewer:lancedb-0.24.3 + image: ghcr.io/lance-format/lance-data-viewer:lancedb-0.29.2 environment: DATA_PATH: /data volumes: @@ -114,7 +112,15 @@ Port 8080 is the default inside the container. The example maps to 8888 on the h ### Images & registries -- **GitHub Container Registry**: `ghcr.io/lance-format/lance-data-viewer:TAG` +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.29.2`) | +| `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 @@ -144,6 +150,19 @@ 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: + +```bash +pip install -c backend/constraints-0.29.2.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 all six. + ### Development workflow ```bash @@ -152,7 +171,7 @@ docker ps -q | xargs docker stop # Rebuild after code changes (with specific Lance version) docker build -f docker/Dockerfile \ - --build-arg LANCEDB_VERSION=0.24.3 \ + --build-arg LANCEDB_VERSION=0.29.2 \ -t lance-data-viewer:dev . # Run in background @@ -168,20 +187,17 @@ curl http://localhost:8080/healthz | jq '.lancedb_version' ## Supported Data Types ### ✅ Fully Supported -- **Standard types**: string, int, float, timestamp, boolean, null -- **Modern vectors**: `Vector(dim)` fields (LanceDB 2024+ style) -- **Fixed-size vectors**: `fixed_size_list[N]` (e.g., CLIP-512) -- **Structured data**: nested objects, metadata fields +- **Standard types**: string, int, float, binary, timestamp, boolean, null +- **Fixed-size vectors**: `fixed_size_list[N]` (e.g., CLIP-512), as written by `Vector(dim)` fields +- **Variable-length vectors**: `list` and `list` +- **Structured data**: nested structs and lists, including vectors inside them - **Indexed datasets**: properly created with IVF/HNSW indexes ### ⚠️ Limited Support -- **Legacy vectors**: `pa.list_(pa.float32(), dim)` - schema only, may show corruption warnings -- **Large vectors**: >2048 dimensions show preview only -- **Corrupted data**: graceful degradation with informative error messages +- **Corrupted data**: the schema stays viewable and rows are replaced with an informative error message ### ❌ Not Supported -- Binary vectors (uint8 arrays) -- Multi-vector columns +- Binary vectors (uint8 arrays), shown as plain lists without vector visualization - Custom user-defined types - Write operations (read-only viewer) @@ -199,4 +215,9 @@ The viewer provides advanced visualization for vector embeddings: - 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 \ No newline at end of file +- Read-only access prevents accidental data modification + +### Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the design constraints and how to +propose changes. Release history lives in [CHANGELOG.md](CHANGELOG.md). \ No newline at end of file