Indexer

Defines the function that will be called to add an index row to the index. May be called multiple times to create multiple index rows for a single document, or not at all to skip a document from being included in the index.

See also the Indexer.Map typealias.

typealias AddIndexRow = (_ key: Any, _ value: Any?) -> Void

Defines the function that will be called when the database documents are indexed.

See also the Indexer.map property.

typealias Map = (_ document: Document, _ addIndexRow: @escaping  AddIndexRow) -> Void

Defines the function used for MapReduce style indexes to perform the reduce sumarization.

See also the Index.reduce property.

If provided, the reduce function will be called when the index is queried to summarize the results of a index.

typealias Reduce = (_ keys: [Any], _ values: [Any], _ rereduce: Bool) -> (Any)

Name of the index

var name: String

Version of the index

Once created, a database index is stored as part of the data in database, for this reason, changes to an index require special handling.

If any part of the map function or reduce function change, the version string should be changed to ensure the index is properly updated. Failure to change this value when updating the code will lead to unpredicable results.

var version: String

Map function that will be called when the database documents are indexed.

A map function’s job is to analyze a database document’s contents and identify key/value pairs to be indexed. A given document can add a single key/value pair, multiple key/value pairs, or no key/value pairs to the index, depending on the data and what the index is indexing. The index is then used to query the database, and controls the sort order of the query results.

Important rules for the map function:

• The function must always produce the same output for the same input

The function’s output must be consistant or the index it builds will not produce valid queries. The function must not use external information or state to make it’s decisions.

• The function must be thread-safe

The indexing will take place in a background thread or threads, and may be parallelized.

• The function cannot change external state

In addition to causing thread-safty issues, it is unpredicable as to when the function is called or what documents are sent to it.

Both the key and value passed to emit can be any JSON-compatible objects such as strings, numbers, booleans, arrays, dictionaries, and null (NSNull)

Sorting:

Sorting in the index depends on the data type of the key. Sorting is done in this order:

• Null
• Boolean: false, then true
• Numbers, in numeric order
• Strings, case-insensitive, following the Unicode Collation Algorithm
• Arrays, compared item-by-item.
• Dictionaries/maps, also compared item-by-item. See warning below.

Details:

Arrays are particularly useful to achieve multiple layers of sorting, since elements are compared in order of their array index. So, all the first array elements are compaired, then all the second elements, etc. The net effect of this type of index can be a sorted structure like:

| Ingredient | Type            |
|------------|-----------------|
| Olive      | Black           |
| Olive      | Green           |
| Olive      | Pimento stuffed |
| Vermouth   | Dry             |
| Vermouth   | Extra Dry       |
| Vermouth   | French          |
| Vodka      | Grey Goose      |
| Vodka      | Stoli           |
| Vodka      | Tito's          |

Dictionaries/maps are a particularly poor type to use for sorting since JSON doesn’t specify any ordering of keys, so the order of items is ambiguous. So while using dictionaries as key is technically possible, it is not recommended.

Values:

Emitting a value is not required, but can improve performance when querying large documents. Values are generally a subset of one or more document properties needed when a query is run against the index; for example to display search results in a grid, or to summarize a child record in a master view. This can avoid the cost of retreiving the entire document to paint a UI needing only a few values. Unlike the key element, dictionaries/maps is very useful type as a value, since they can be used to return multiple document properties in the single value emitted element.

It is not recommended that the entire document be returned as a value, even in cases where the entire document will be needed by the consumer of the index. When querying the index, the Id of the document that generated the index row is always returned as part of the query results. Thus the Id can be used to retrive selected documents. Additionally, there is also the option to return the entire document in the query results as well. Retrieving the document during the query is more efficent in both storage and processing time than adding the entire docuement to the index as a value.

There can be instances when it is useful for the query’s document id to be the id of a different docuement than that which emitted the index row. This can be acheived by emiting a dictionary value where the dictionary contains a key/value pair where the key is _id, and the value is the document id of the document you want to associate with the index row, rather than the source document id.

For example:

let myMap: Indexer.Map = { (document, addIndexRow) in

    // if the source document contains a "related_documents" property
    if let relatedDocuments = document["related_documents"] as? [String] {
        // for each value in "related_documents" (which are related document ids)
        for relatedDocument in relatedDocuments {
            // add an index row with a key of type and id, and a value that changes the query results document id
            // to the related document.
            let key = [type, document.id]
            let value = ["_id": relatedDocument]
            addIndexRow(key, value)
        }
    }
}

let myIndex = Index(name: "myIndex", version: "1", map: myMap)

Using the map above, a query could then be run that would pass a given document Id, then receive back all the documents related to that document.

var map: Map

An optionalReduce function that will be called when a database index is queried to summarize the results of the query.

Reduce functions are the second half of the map/reduce technique. They’re optional, and less commonly used. A reduce function post-processes the indexed key/value pairs generated by the map function, by aggregating the values together and is commonly used to provide counts, totals, or averages.

A reduce function takes an ordered list of key/value pairs, the keys and values from the index, and aggregates them together into a single object, then returns that object.

For indexes that do not emit a value, the value array will be an array of NSNull objects.

Rereduce

The rereduce flag is used when querying large data sets. When the data set is large the underlying system will break the map/reduce into smaller chucks, run the reduce on each chunk, then run reduce again on the reduced chunks. When this happens, the rereduce flag will true, the key array will be empty, and the value array will contain the partial reduced values.

Example

// Given a map function that emits the "type" of each document...
let myMap: Indexer.Map = { (document, addIndexRow) in

    if let type = document["type"] as? String {
        addIndexRow(type, nil)
        }
    }

    // This reduce function will summarize those types, and output a dictionary
    // which contains each unique type and the total number of documents of that type.
    let myReduce: Indexer.Reduce = =  { ( keys, values, rereduce) in

    var result: [String: Int] = [:]

    // if this is not a rereduce
    if !rereduce {
        // count each unique key value
        if let sKeys = keys as? [String] {
            for key in sKeys {
                var count = result[key] ?? 0
                count += 1
                result[key] = count
            }
        }
    } else {
        // This is a rereduce, then our value array will be an array of
        // dictionaries of unique key values and their counts from above.
        if let counts = values as? [[String: Int]] {
            // for each result array
            for count in counts {
                // for each key in the result
                for key in count.keys {
                    // count and compile a final result dictionary
                    var count = result[key] ?? 0
                    count += 1
                    result[key] = count
                }
            }
        }
    }

    // return the unique key values
    // Note that regardless of the rereduce flag the result is the same data type. This must always be the case.
    return result
}

let myIndex = Index(name: "myIndex", version: "1", map: myMap, reduce: myReduce)

var reduce: Reduce?