Start here2 min read

Getting started

From a clone to a real finding about a real table.

1. Install and run

bash
make setup     # python deps and web deps
make dev       # API on :8000, console on :3000

Run make setup again after any git pull. A pull updates the dependency manifests without installing anything.

Open http://localhost:3000/console. On a machine with nothing configured it will tell you there is no database yet, and point at settings — which is where to go next.

2. Point it at a database

Open Settings, paste the path of a directory containing .lance tables, and press Check. It will tell you what is actually there before you commit to it:

2 table(s): moments, segments

Press Add & use. The catalog is repointed in place — nothing restarts, and the table list appears immediately.

No database to hand? Build the demo corpus with make ingest LIMIT=8, which downloads a handful of conference talks and assembles them into two Lance tables. It is gigabytes and takes a while; the console works against any Lance directory, so borrow one if you have it.

3. Look at a table

Pick a table in the rail. The Schema tab shows every column and the split between what a scan reads and what sits in blob side files. Note the figure in the header — that is what looking at this table just cost.

4. Find out what is wrong with it

Open Insights. This is where the console says what it worked out for itself:

vector has no vector index Every similarity search over vector scans all 1,114 rows and reads each 768-dimension vector to do it. That is fine at this size and stops being fine as the table grows.

Every finding carries its evidence — the column, the dimensions, the row count, the bytes a scan would move. None of it was generated by a model; it is arithmetic over metadata Lance already reports.

5. Prove it

Open Query, choose vector, and run a search. The diagnosis card names the access path and what it read:

RETURNED 10   TIME 1 ms   READ 3.5 MB   IOS 21
brute-force vector scan — Every row's vector is read and compared.

Now switch to full text and search for a word. Same table:

RETURNED 25   TIME 2 ms   READ 100 KB
inverted index — Full-text search used the inverted index rather than reading the column.

Thirty-five times less, because one of those columns has an index and the other does not. That is the finding from step 4, in bytes.

Press + python to get the script that reproduces it outside this app.

Where to go next