Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) - Manual (Page 482)

C H A P T E R 1 1
Data Storage and Retrieval
11-50 Using Newton Data Storage Objects
Instead of using single values for the indexPath , beginKey , beginExclKey ,
endKey , and endExclKey slots in the query spec, the Query method accepts
arrays of keys or values as these arguments when it works with a soup having a
multiple-slot index. The first key in the array is the primary key; subsequent lower-
order keys, if they are present, are the secondary key, tertiary key, and so on, up to
a total of six keys per array.
To get a better idea of how queries evaluate multiple-slot key selectors, consider
how the
beginKey value in the following code fragment would work with the
example data:
myQSpec := {indexPath: ['last,'first,'num],
beginKey:["Perry","Bruce",5]}
Querying the example data using this specification returns a cursor that initially
references the following entry:
{last: "Perry", first: "Daphne", num: 7}
First, the query finds the primary key value of "Perry" in the index, skipping
over the "Bates" entry in the process of doing so. Next, the query searches for an
index value identical to the secondary key "Bruce" , skipping over the
"Barbara" entry in the process of doing so. Finally, the query searches for an
index value identical to the tertiary key value 5 . Because an entry having this value
is not found, the cursor is positioned on the next valid entry in index order, which
has the tertiary key value
7 .
When specifying strings as bounding values for queries, don’t forget that the
beginKey , beginExclKey , endKey , and endExclKey slots in a query spec
specify identical matches only. For example, the key value "P" is not identical to
the key value "Perry" .
When an identical index value cannot be found for a key specification, subordinate
key values have no effect. For example, if the primary key value is not matched, the
secondary and tertiary key values have no effect.
To demonstrate these points, imagine that you wrote the query spec in the previous
example a bit differently. Instead of specifying a value of
"Perry" for the primary
element in the beginKey array, assume you specified a value of "P" . This change
would make the query spec look like the following code fragment:
myQSpec := {indexPath: ['last,'first,'num],
beginKey:["P","Bruce",5]}
Querying our example data using this specification returns a cursor that initially
references the following entry:
{last: "Perry", first: "Barbara", num: 3}