Data Storage and Retrieval

Using Newton Data Storage Objects

A multiple-slot query can be performed only on a soup that has a multiple-slot
index generated against the same set of keys in the same order as the query spec.
For information on creating an index, see "Registering and Unregistering Soup
Definitions" beginning on page 11-33 and "Adding an Index to an Existing Soup"
beginning on page 11-36. For a description of the data structure that defines a
multiple-slot index, see "Multiple-Slot Index Specification Frame" (page 9-6) in
Newton Programmer's Reference.

In a general sense, queries on multiple-slot indexes are specified like queries on
single-slot indexes and behave the same way. The "differences" you'll encounter
are usually the result of misunderstanding how multiple index keys are used to sort
and select indexed entries.

For purposes of discussion, assume that you have a soup containing the entries in
the following code fragment, and that you want to sort these entries alphabetically
by last name and then by first name:

// entries used for all examples in this section
{last: "Perry", first: "Bruce", num: 1}
{last: "Perry", first: "Ralph", num: 2}
{last: "Perry", first: "Barbara", num: 3}
{last: "Perry", first: "John", num: 4}
{last: "Bates", first: "Carol", num: 5}
{last: "Perry", first: "Daphne", num: 7}

A single-slot index sorts entries according to the value held in a single slot that you
specify when the index is created. In contrast, a multiple-slot index may consider
the values of multiple slots when sorting entries. It's important to understand that
either kind of index imposes only one sort order on the indexed data, regardless of
the number of slots examined to arrive at that order. A query on index values
evaluates its associated entries in this order, and the cursor generated by this query
iterates over its entries in this order, as well.

The first example illustrates how the entries in the example data could be sorted by
a single-slot index. For purposes of discussion, assume that these entries are
indexed on the value that each holds in its

last

slot, as specified by the single-slot

index spec in the following code fragment:

// single-slot index on string data from 'last slot
{structure:'slot, path: 'last, type:'string}

Sorting the entries according to the value each holds in its

last

slot isn't very

useful because all of the entries except one hold an identical value in this slot.
Unfortunately, sorting the entries on the value of another slot does not produce a
useful ordering, either: an index on any other single slot sorts the

"Bates"

entry

in the midst of all the

"Perry"

entries.