Document the row / record / TermsAndValues levels and the two senses of "index"

[drametwally]

Docs only, two vocabulary levels that keep getting mistaken for duplication.

Rows and records

Four names sit close enough together to read as duplicates, and the record/TermsAndValues pairing has now been flagged twice as if one of them were redundant. They are four levels of one thing:

• A row is what a searchable structure stores: a record plus its metadata, the extra data a filter matches on. It is identified by a rowNum, the handle the internals pass around in place of the row.
• A record is the feature data of a row — a concept, not a type. It can be a vector, a time series, a histogram, a sparse (multi-)set, or a sequence of terms. RecordType names which shape, and a comparator and a structure pair up by agreeing on one.
• TermsAndValues is the public structure a record arrives in: String[] terms and float[] values, which between them express every shape depending on population. Terms alone is a sequence, values alone is dense, both is sparse.
• LongTermsAndValues is the internal form of the same pair, terms hashed to long with the comparator-derived uniValue cached alongside.

Stating it also answers why the enum is RecordType and not TermsAndValuesType.

README.md read "A record is a TermsAndValues", which flattens the two levels into each other. It now reads "A record reaches USSI as a TermsAndValues" — the same instruction for someone embedding the library, without the conflation.

Two senses of "index"

This one is a correction to my own audit. I had flagged NearestNeighborSearchIndex as misnamed because it holds List<Index> and List<Cache>, making it the engine rather than an index, and proposed renaming it to SimilaritySearchEngine.

That reasoning missed that the word covers two levels, and both are right in their place. The library as a whole is an index — that is the sense the project's own name carries in Uber Similarity Search Index — while an Index is one searchable structure inside it, a sibling of Cache. Renaming the facade would have left a library called an index with nothing named one at the top, and broken every embedder's entry point to do it.

So the name stays and the real confusion, one word covering two levels, is written down instead:

So the facade holding indexes rather than being one is not a contradiction. A reader who expects NearestNeighborSearchIndex to extend Index has the narrow sense in mind; nothing does, and nothing should.

Checked, not guessed

The population rules were read back off TermsAndValues.isDenseFeature, isSparseFeature, and isSequence. The facade's composition was read off its field declarations: implements AutoCloseable only, with List<Index> indexes and List<Cache> graduatingCaches.

One thing deliberately left out: why we say "active cache" rather than the SPARS paper's "live cache" — the engine owns one active cache plus zero or more graduating caches, and graduating caches are still searched, so "live" would imply the others are dead. That note only makes sense once the paper is cited here, so it rides with the terminology-alignment PR.