Find

The Cloud CMS Find Service lets you discover and retrieve content using combinations of its three primary content retrieval mechanisms.

These mechanisms are:

Query (powered by Mongo DB)
Search (powered by Elastic Search)
Traversal (provides Graph Traversal)

A "Find" operation provides a way for you to execute a single API lookup that runs one or more of the above and composes them into a single result set.

How it Works

When you make a "Find" call, you provide a recipe containing at least one query, search or traversal. The Find engine then executes these separately and composes a unified result set of the results.

In a way, you can think of this a bit like a Venn diagram. Each query, search or traversal runs on its own and the overlap (or union) of the operations is what gets handed back.

Using a "Find" call, you can do things like:

Find any nodes where price is greater than 10.00 and less than 15.00 (this uses Mongo DB) and also has the word awesome somewhere in it's binary attachment (this uses Elastic Search).
Find any nodes similar to the above that are at most 2 hops away from a starting node via the a:child association or relationship.

When traversal is being used in conjunction with search and query, a good way to think about things is to begin with your content graph. The content graph consists of content instances connected together via associations.

A traversal that searches a depth of 1 for a given association type would essentially carve out a set of nodes against which the subsequent search and query would be executed. In effect, this produces a "shape" around a center node that defines a neighborhood of content that will be searched or queried.

A traversal that searches a depth of 2 would carve out a bigger space and would result in a bigger result set for the same search and/or query operations performed on top of it.

Permissions

Since the Find API uses the Query, Search and Traversal APIs to produce its result set, the result set itself will also be permissioned just as the underlying APIs are. As such, the Find API respects the underlying permissions and authorities that have been granted to the objects that are considered result candidates. Authorities are checked before content is retrieved which means that two people could execute the same query and get different results.

Permissions are baked into Cloud CMS all the way down to the core. If you need to get back the full set of content objects for purposes of synchronization or anything else, make sure that you have sufficient authorities to do so.

Find Nodes (Search and Query)

To perform a composite lookup using Search and/or Query, use the following:

POST /repositories/{repositoryId}/branches/{branchId}/nodes/find

The content type should be application/json and the JSON payload should consist of configuration blocks for search (if you want a search to be performed) and/or query (if you want a query to be performed). If only search is provided, then only a search will be performed and the performance will be similar to a straight Search API call. If only query is provided, then only a query will be performed and the performance will be similar to a straight Query API call.

The JSON payload should look like this:

{
    "query": {
        ... Query Block (Mongo DB)
    },
    "search": {
        ... Search Block (Elastic Search) or string for full-text search
    }
}

Find around a Node (Search, Query and Traversal)

To perform a composite lookup using Traversal, Search and/or Query, use the following:

POST /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/find

The traverse block is required for this method. If either search or query are provided, their result sets will be intersected along with the traversal space to compose the final result set.

The JSON payload should look like this:

{
    "query": {
        ... Query Block (Mongo DB)
    },
    "search": {
        ... Search Block (Elastic Search) or string for full-text search
    },
    "traverse": {
        ... Traverse Block (Traversal) 
    }
}

The results that are returned from a query call are identical in structure to those returned by a search or by any recordset API method in Cloud CMS. As such, they contain full pagination information, allowing you to limit the number of objects that come back and the starting location within the database.

Smaller sets perform faster so be mindful of this with your calls.

As with all Cloud CMS queries, you control pagination via request parameters. These include skip and limit. Pagination also allows you specify sort information to control the result set order.

For more information on pagination, please see our documentation on Pagination.

For information on Query, Search and Traversal, please visit:

Example #1

POST /repositories/{repositoryId}/branches/{branchId}/nodes/find

{
    "query": {
        "category": "appliances",
        "price": {
            "$gt": 10.00,
            "$lte": 15.00
        }
    },
    "search": "awesome"
}

Example #2

Here is an example of a Find API call where we find all content items with category equal to appliances, a price greater than 10.00 and less than or equal to 15.00 and with the word awesome somewhere in the document text. Here we also traverse only depth 2 away from a node following outgoing associations of type my:works-with and handing back nodes of type my:product.

POST /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/find

{
    "query": {
        "category": "appliances",
        "price": {
            "$gt": 10.00,
            "$lte": 15.00
        }
    },
    "search": "awesome",
    "traverse": {
        "associations": {
            "my:works-with": "OUTGOING"
        },
        "depth": 2,
        "types": [ 
            "my:product" 
        ]
    }
}