In order to make index builds faster, we made interface changes to SortedDataInterface to accept KeyStrings (see SERVER-41719 and SERVER-41720).

This introduced some consequentially confusing API problems, which are summarized below. This ticket is an attempt to capture those issues:

• insert() takes a KeyString which is required to have a RecordId appended.
  • This string is not necessarily how the index implementation stores the entry. Most indexes use a KeyString+RecordId key. The "_id" index, however, stores the RecordId as the value, not in the key of the index entry, and strips away the RecordId from the KeyString for the key.
  • Ideally, insert would take two arguments, a key and value, but accepting a single parameter was chosen as an optimization to avoid making extra copies of the index key just to append a RecordId in the common case
• seekExact() takes a KeyString which is required to not have a RecordId appended.
  • This is confusing because it contradicts the API requirement of the insert() function, which is the opposite. In fact, to "seek exactly" should really return nothing for indexes that store the RecordId in the key, because it would never be possible to pass in a KeyString query with a RecordId, per the API definition.
  • seekExact today really does "seek to a prefix", which isn't much different than seek, and could be a candidate for removal.
  • This is mostly captured by SERVER-43176, which attempts to restrict seekExact to the _id index.
• Callers are now responsible for understanding how to construct KeyStrings for inserting and querying, both versions are different and in some cases neither represent how the data is actually stored.
  • For example, we construct KeyStrings with discriminators to pass into seek, but discriminators are not stored in the storage engine. SERVER-43059 captures this problem, mostly.