Data Storage and Retrieval

Using Newton Data Storage Objects

the use of internationalized sorting order

queries on multiple-slot indexes

Querying Multiple Soups

11

Soups having the same name can be associated logically by a union soup object. To
retrieve entries from all the available soups in a union, just send the

Query

message to the union soup object.

You must query differently named soups separately, however. For example, before
scheduling a meeting, you might send the

Query

message to the

ROM_CardfileSoup

soup for information regarding its participants, and send

another

Query

message to the

ROM_CalendarSoupName

soup to determine

whether you have conflicting appointments at the proposed meeting time.

Entry aliases provide a handy way to save references to soup entries. You can use
entry aliases to reference entries from different soups more easily. For more
information, see "Using Entry Aliases" on page 12-7.

Querying on Single-Slot Indexes

11

This section provides code examples illustrating a variety of queries on single-slot
indexes. For more information on indexes, see "Introduction to Data Storage
Objects" on page 11-2 and "Indexes" on page 11-8.

The following code fragment presents an example of the simplest kind of index
query--it returns all entries in the soup:

local myUSoup := GetUnionSoupAlways("mySoup:mySig");
local allEntriesCursor := myUSoup:Query(nil);

When

nil

is passed as the query spec, as in the example above, the query result

potentially includes all entries in the soup. The cursor generated by such a query
returns entries in roughly the same order that they were added to the soup;
however, this sorting order is not guaranteed because the system recycles the values
it uses to identify entries internally. The only way to guarantee that entries are
sorted in the order they were added to a soup is to index them on your own time
stamp slot.

Most situations will require that you query for a subset of a soup's entries, rather
than for all of its entries. That is, you'll want to include or exclude entries
according to criteria you define. For example, you might want to find only entries
that have a certain slot, or entries in which the value of a specified slot falls within
a certain range. The next several examples illustrate the use of single-slot index
queries for these kinds of operations.

To find all entries that have a particular slot, specify a path to that slot as the query
spec's

indexPath

value. Note that in order to query on the presence of a