Find
The Cloud CMS Find Service lets you discover and retrieve content using combinations of
its three primary content retrieval mechanisms.
These mechanisms are:
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 wordawesome
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 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
andlimit
. 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 toappliances
, a price greater than 10.00 and less than or equal to 15.00 and with the wordawesome
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 toappliances
, a price greater than 10.00 and less than or equal to 15.00 and with the wordawesome
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"
]
}
}