adityamparikh opened a new pull request, #184:
URL: https://github.com/apache/solr-mcp/pull/184
## What
Adds `docs/tutorial.md` — a hands-on walkthrough taking a reader from an
empty Solr to a
designed, queryable collection, entirely through natural-language
conversation with an
assistant. Linked from the README documentation index.
## Why
The docs cover *how to connect a client* and *what each tool does*, but
nothing explains
**why field types decide which questions are answerable**. That gap matters
here more than in
a normal Solr context: the assistant will happily index anything schemaless,
and the user has
no obvious signal that they've traded away faceting and sorting until a
question quietly
fails.
So the tutorial indexes the same 61-document dataset twice — once letting
Solr guess, once
choosing types on purpose — and puts the two side by side:
| | schemaless | designed |
|---|---|---|
| Documents indexed | 61 of 61 | 61 of 61 |
| `platform` type | `text_general` | `string` + docValues |
| `imdb_rating` type | `pdoubles` (multi-valued) | `pdouble` |
| *"breakdown by platform"* | fails | `Netflix 20, Amazon Prime Video 20,
HBO Max 7, …` |
Same data, same question, same tool. The only difference is that someone
decided what the
fields meant.
## Verification
Every factual claim was checked end-to-end against Solr 9 in SolrCloud mode,
driven through
the MCP server over STDIO — not written from what the tool signatures imply:
- the guessed types (`text_general`, `pdoubles`, `plongs`) and the
array-wrapped documents
- all eight search examples and their result counts (1, 2, 20, 31, 15,
status 33/28, top-rated
Game of Thrones 9.2, combined 39)
- the facet buckets quoted in the text
- `check-health` reporting 61 docs, and `get-collection-stats` exposing the
cache hit ratios
the tutorial invites the reader to ask about
## Known issues, documented rather than hidden
A reader following the steps will hit both of these, so the tutorial names
them and links the
issues instead of quietly routing around them:
- **#182** — faceting a query that matches nothing throws
`ClassCastException: ArrayList cannot be cast to NamedList`. This is
exactly what the
schemaless pass runs into.
- **#183** — `create-collection` binds collections to the shared `_default`
configset, so
schemaless guesses leak into every later collection and `add-fields` then
fails with
`Field 'x' already exists`. This is why the tutorial resets Solr midway,
and the reset is
called out as a workaround rather than presented as normal practice.
If either is fixed, the corresponding section should be trimmed — they're
marked clearly
enough to find.
## Notes for review
- Uses the raw `shows.json` from `src/test/resources/` via its GitHub URL.
Referencing a test
resource from user docs is a little irregular; happy to move the dataset
somewhere more
deliberate if preferred.
- Docker examples follow the existing `docs/clients/*.md` convention of a
locally built image
rather than a registry reference, since no official image is published yet.
- `**/*.md` is RAT-excluded and the existing `docs/*.md` carry no license
header, so this
follows suit.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
