MAP Query Engine

MAP Query Engine

The MAP Query Engine supports rich graph database type query capabilities (e.g., Open Cypher) for navigating the nodes and links (holons and holon relationships) of the MAP Holons information store.

Query evaluators accept SmartCollections as inputs and produce SmartCollections as outputs. Thus, they may be composed together to provide powerful capabilities to query the MAP information graph.

SmartCollections consist of a collection of SmartReferences -- the in-memory representation of SmartLinks. SmartReferences enable filtering, sorting and pagination operations to be performed without having to retrieve the referenced holon. In cases where, the referenced holon DOES need to be fetched, the fetching is performed by the MAP Holons Cache Manager. The Cache Manager returns holons that, if not already present in the cache, are first fetched from the holochain persistence tier. This minimizes fetches to the backing store.

Both query types include filtering capabilities. The following figure shows an example of how Human Agents could visualize and define filters.

Query semantics are specified by QueryInput structures that can thought of as representing clauses within a query expression. Initially, the MAP Query Engine will support RelationshipQuery and AnchoredCollectionQuery clauses. The RelationshipQuery clause is shown below

The high-level flow for evaluating queries is shown in the following diagram:

For example, suppose a Book holon type had title, publication_date, and rating property types. The authors role_name from Person to Book may offer different sort orders for retrieving the Books a given Person has authored:

1. by publication_date, Ascending (oldest to newest)
2. by publication_date, Descending (newest to oldest)
3. by rating, Descending, then by title, Ascending.

Holochain HDK get_links()

Holochain's get_links() function offers the following filtering options on Links:

• by LinkType (all SmartLinks share the SmartLink LinkType)
• by link added time (before/after)
• by author's AgentPubKey (the id of the Agent cell that created the link)
• by Link tags that start with a supplied tag_prefix

It returns a vector of links that match the filtering conditions specified in the GetLinksInput struct):

pub struct GetLinksInput {
    pub base_address: holo_hash::AnyLinkableHash,
    pub link_type: LinkTypeFilter,
    pub tag_prefix: Option<LinkTag>,
    pub after: Option<Timestamp>,
    pub before: Option<Timestamp>,
    pub author: Option<AgentPubKey>,
}

In effect, each parameter specifies a filter condition and a Link is returned if and only if it meets all of the filter conditions provided. The tag_prefix filter condition uses starts-with (not contains) logic. Only Link's whose tag property starts with tag_prefix satisfy this condition.

Suppose we have the Person Holon for Fritjof Capra and we want to find all of the books he has authored:

• base_address would be set to the ActionHash of the Person Holon for Fritjof Capra.
• link_type would consist of SmartLink
• tag_prefix leverages the same encoding rules as described above

This includes only links whose tag starts with the specified tag_prefix. Since the source HolonType for the authoring relationship is Book and we want to navigate from Person to Book, the desired direction would be set to TargetToSource and the desired role_name would be author_of.

Unpack Link to QueryResult

This step maps the vector of holochain links returned by get_links() into the QueryResultHeader and Element representations shown in the diagram above. This puts them into a more usable representation for filtering, sorting and pagination.

Filter

In this stage, the filter_spec provided for this query is evaluated for each Element in the Query result. Type-specific comparator operators perform the specified comparison operations. Results of individual filter comparisons are combined based on the Boolean operator associated with each filter element. If the final result evaluates to false, that element is removed from the query results.

Note that as long as all of the property names referenced in the filter spec are included in the SmartLink's access_path, the filter evaluations can be performed without having to retrieve the to-holon referenced by the SmartLink. If any property is required for filtering that was not included in the access_path, the to-holon is fetched via the Holon Cache Manager.

After all elements have been evaluated, only elements that pass the filter conditions will remain in the query result.

Sort

Once filtering is completed, the remaining elements can be sorted based on the OrderByClause included in the QueryInput. As with filtering, if values for any property specified in the OrderByClause was NOT encoded in the access path, the to-holon is fetched via the Holon Cache Manager.

Paginate

If the number of filtered and sorted elements remaining in the query result exceeds the limit specified in the QueryInput, only the first limit elements are returned in the result. The result can also include result_count value so the client knows how many elements satisfy the filter condition. A get_next_page Affordance is also included in the query result. It contains the sort key and to-holon address for the last element returned in the results.

Retrieving Subsequent Pages of QueryResults

The client can invoke the get_next_page request returned as a result of the previous call. The stateless server principle means that the server will no longer have the query result from the previous query, so the execution steps will need to be repeated. Because of the nature of distributed, eventually consistent systems, the links returned by Holochain could be different.