Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) User Manual

Page 474

C H A P T E R 1 1

Data Storage and Retrieval

11-42

Using Newton Data Storage Objects

The query passes the entire entry to the

validTest

method, rather than just the

value of the indexed slot. The next code example reads the entry’s

aSlot

and

otherSlot

slots in order to compare their values:

// select entries for which aSlot > otherSlot

local myCursor :=

mySoup:Query({endKey:

aKeyValue

validTest: func (entry)
begin

entry.aSlot > entry.otherSlot

end});

Querying for Tags

In order to select soup entries according to their associated tag values, you need to
include a tags query spec frame in the

tagSpec

slot of the query specification

frame passed to the

Query

method. In addition to specifying one or more tags used

to select entries, the tags query spec can specify set operators such as

not

any

equal

, and

all

to create complex filters based on tag values. For a complete

description of the tags query spec frame, see “Tags Query Specification Frame”
(page 9-13) in Newton Programmer’s Reference.

You cannot query for tags on a soup that does not have a tags index. This index is
usually specified by your soup definition and created along with the soup, but it can
be added to an existing soup if necessary. Note that each soup or union soup has
only one tags index; if you add a tags index to a soup that already has one, it
replaces the original tags index. For more information, see “Tags Index
Specification Frame” (page 9-8) in Newton Programmer’s Reference.

The next several examples presume that the

mySoup

soup has a tags index on the

labels

slot. Note that queries need not specify the path to the slot from which tag

values are extracted—in this case, the

labels

slot—because each soup has only

one tags index and its index path is specified when the tags index is created.
However, because a soup or union soup is allowed to have multiple soup indexes,
queries must specify a path to the indexed slot; hence, these examples also presume
that the

mySoup

soup has a soup index on the

name

slot.

The presence of any tag specified by the

any

set operator is sufficient to include its

entry in the results of the query that uses this operator. For example, the following
query selects entries having either the symbol

'flower

'tall

in the

labels

slot. Entries not marked with at least one of these symbols are not included in the
query result.

local myCurs := mySoup:Query({indexPath:'name,

tagSpec: {any:['tall, 'flower]}});

The

equal

set operator specifies a set of tags an entry must match exactly to be

included in the query result. The query in the following example uses the

equal