Data Storage and Retrieval

Using Newton Data Storage Objects

This time around, the query again skips over the

"Bates"

entry in the process of

positioning the cursor at index value

"P"

. However, because no entry holds a

primary index key value of

"P"

, the cursor stops at the next valid entry in index

order. Further, because an identical index value was not found for the primary key
specification, the secondary and tertiary key selectors have no effect at all. Thus
the cursor stops on the first index value found after the position that

["P","Bruce",5]

would occupy if it were present in the index data.

When an element of an array in a query spec is missing or

nil

, the

Query

method

does not test subordinate key values specified by the array. For example, the
presence of the

nil

value in the

endKey

specification

{endKey : ["bob",

nil, 55]}

makes it equivalent to the

{endKey : ["bob"]}

specification.

One result of this behavior is that it is impossible to make a query ignore higher-
order sort keys while still testing on lower-order keys. For example, it is meaningless
to specify a value such as

[nil,

]

for the

beginKey

,

beginExclKey

,

endKey

, or

endExclKey

slot in a query spec--the

nil

-value primary element

specifies that the query is to ignore subsequent elements of the array.

If you want to be able to ignore key specifiers in a query spec selectively, you need
to define for your entries a default "

nil

-equivalent" value that does have a position

in index order. For example, you could use the empty string (

""

) for string key

values, either of the values

0

or

MININT

for integer key values, and the null

symbol (

'||

) for symbolic key values.

Further, the presence of a

nil

-value index key in an entry suppresses the

evaluation of lower-order keys in that entry for sorting in the multiple-slot index.
For example, the entries in the following code fragment sort to the same position in
the multiple-slot index because as soon as the system encounters the

nil

key value

in each entry's

secondary

slot, it does not attempt to sort that entry any further:

{primary: "foo", secondary: nil, tertiary: "bar"}
{primary: "foo", secondary: nil, tertiary: "qux"}

Querying explicitly for

nil

key values (

nil

-value slots) is not supported. Your

entries' indexed slots must hold non-

nil

values to participate in queries.

For cursors generated against multiple-slot indexes, the cursor method

GoToKey

accepts arrays of keys as its argument. You can use this method to experiment with
multiple-slot key specifications.

Similarly, for queries on multiple-slot indexes, the input passed to the

indexValidTest

function is an array of key values, with the first key in the

array being the primary key, followed by any subordinate key values held by the
entry being tested.