Would it be better for the Table.Search* functions to be named Table.Seek* or Table.Fetch* instead? I think that is at least true for Table.SearchAll, for the reason below.
In the case of Table.Search and Table.SearchBatch (and similarly Database.Search), the word "Search" is OK, it does make sense, since there is some matching going on, there are criteria. (I would still prefer "Seek" or "Fetch" in those cases, since those words seem to describe more accurately what is going, i.e. filtering a sequence, but that may be subjective and perhaps it doesn't matter.)
In the case of Table.SearchAll, there is no searching--no matching, no criteria. Here "Seek" or "Fetch" are both clearly better than "Search", which makes the actual purpose less obvious and possibly confusing. ("What are you searching for? I'm searching for everything!"--That doesn't really make sense.)
There seems to be some confusion (maybe just mine) in the documentation for Table.SearchBatch. I can't follow it.
First, we have
index - name of a unique index. Case-insensitive.
keys - key values specifying the search criteria.
fields - list of fields to return. May be empty.
The method attempts to locate records that match the specified search criteria. [This could be omitted since it's obvious and/or implicit under Parameters.]
The index parameter is the name of a unique index. [Unnecessary repetition.] If the index is not found or is not unique, the method will fail. [Crucial.]
The keys parameter provides the key values specifying the search criteria. [Again just repetition.] The key values are interpreted according to the index type. [Crucial, and should possibly stand as a separate paragraph so that its relation to what follows is more obvious.]
The bits in bold are what I'm focussing on. [The comments in brackets above are secondary, not the main point here.]
So far so good, and clear.
Next there are two sections which explain that last sentence, "The key values are interpreted according to the index type", for BTREE / BTREEDUP / BTREEDUPNULL / BTREENULL indexes on the one hand, and RTREE on the other.
Wait a second... Here's the first confusing thing. The documentation has aleady said that the index named in the index parameter must be unique. Now we have the possibility that "the index" may not only be BTREE or BTREENULL, but also BTREEDUP or BTREEDUPNULL, that is, not unique. Huh? What does "the index" mean here then?
BTREE / BTREEDUP / BTREEDUPNULL / BTREENULL indexes interpret key values as the starting point of the search.
If we weren't already confused about what "indexes" means here (it apparently can't mean the index used as the index parameter), maybe the meaning here would likewise be clear.
In general, how do "indexes" relate to the search fields? Well, this is exactly what the section is trying to explain! Yes, but it doesn't do a very good job! I have no idea.
The rest is (maybe, consequently) no clearer, at least to me...
For an index that uses a single field: ...
For an index that uses multiple fields: ...
If the index allows duplicates and there are multiple records sharing the values of the index fields on which the sequence should start, the sequence is guaranteed to read through all of these records.
The index may revert the ordering in one or more fields via field options.
[Should "revert" there mean "reverse", or something else? Anyway probably not "revert"--that is, to put something back the way it was.]
Next in the same section:
The values in the keys parameter that do not correspond to any of the fields used by the index are ignored.
This seems crucial, but I don't understand it. Does it mean that we can't search for any values not involved in some BTREE* index (possibly with duplicates)? (If so, this sentence should probably be promoted higher, possibly under Parameters). How does that index (or possibly, how do these indexes) relate to the index parameter, where the index must be unique?
The order of records in the returned sequence proceeds from smaller to larger values of the index fields according to the index field options.
Here, I think "index fields" does refer to the index parameter, and "index field options" means, for example, ASC/DESC, CASE/NOCASE, ACCENT/NOACCENT, SYMBOLS/NOSYMBOLS.
If that's right, I was initially thrown off the right path by one of the examples further below:
// list all records Manifold.Values keys = new Manifold.Values(); app.Log("Listing all records ordering by name"); ListSequence(app, table.SearchBatch("name_x", keys, fields));
Here "ordering by name" could be better worded: it's actually ordering by the index "name_x", with whatever fields that includes (maybe just one, called "name") and the associated options (maybe none). (In other words, this is not necessarily or always the same as ordering by the field called "name".)
It would also be worth explaining out loud, either in this example, or higher up, that if an empty Manifold.Values() collection is passed as the keys parameter, then we get all records (if I'm reading that right).