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.

[object Object]

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.

[object Object]

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.

[object Object]

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.

[object Object]

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 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).

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

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.

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" 
        ]
    }
}