Data Storage and Retrieval

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}