This topic shows you how to use Jahia’s Augmented Search GraphQL API. The API requires you to have Augmented Search installed and running.
For security reasons, the GraphQL API is closed even if nodes have public read permissions. For information on opening the API and making it usable for your application, see Setting up authorization.
This section shows you how how to create a basic query, and specify sort, basic and advanced filters, and facets options.
The section shows you how to create a basic query. The examples use the Digitall demo website that is bundled with Jahia.
A search query is composed of several parts:
searches wrapper specifies siteKey, language and workspace properties and allows you to have multiple search queries which execute at the same time. Here’s an example of what the start of your query might look like.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
...
}
}
}
q which stands for query and is the only mandatory parameter. Here’s an example of using the q parameter.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(q:"news") {
took
totalHits
hasMore
hitsOnPage
hits {
node {
name
}
lastModified
lastPublished
lastModifiedBy
lastPublishedBy
displayableName
}
}
}
}
}
searchIn parameter as shown below. By default (if you don’t provide a searchIn parameter), the search is performed in both files and content indices.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(q:"news", searchIn:CONTENT) {
took
totalHits
hasMore
hitsOnPage
hits {
node {
name
}
lastModified
lastPublished
lastModifiedBy
lastPublishedBy
displayableName
}
}
}
}
}
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(
q:"news"
searchIn:[CONTENT]
limit:2
offset:0) {
took
totalHits
hitsOnPage
...
}
}
}
}
Now that you know how to write a basic text search query and use constraints, let’s look at some additional functionality which will help you refine your search further.
Sort just requires two ingredients: a property to sort on and a sorting direction. Here’s an example of adding sort on jcr:title to a query that sorts in descending order.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(...
sortBy:{property:"jcr:title", orderType:DESC}) {
...
}
}
}
}
The following types of filters are supported:
Let’s look at some filters in detail. The nodeType filter filters out documents that don’t match the specified node type. You can also indicate whether you want to include subnodes or not. The example filters on page nodes and their subnodes. The author filter only takes one parameter value, which is a string representing a user’s name.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(...,
sortBy:{...},
filter:{
nodeType:{type:"jnt:page", includeSubNodes:true}
author:{value:"root"}}}) {
...
}
}
}
}
A date filter can take a string representation of a date or date math expression. Three constraint types are available:
equal constraint, before and after are ignored by your search.You can use a single filter or combine all four filters together for added flexibility. Here’s an example of a query that uses two filters.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(...,
sortBy:{...},
filter:{author:{value:"root"}, published:{before:"now-1d/d"}}) {
...
}
}
}
}
Advanced filtering gives you full control of the property you want to filter on. You use a custom object to specify term, dateRange and numberRange filters. This allows you to have one or more filters of the same type (term, number range, date range), which can be ANDed or ORed together for greater flexibility. Here’s an example of a term filter.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(...,
sortBy:{...},
filter:{
custom:{
term:[{operation:OR, terms:[{field:"jcr:createdBy" value:"root"}]}]
}
}
{
...
}
}
}
}
In this case, the result set is filtered to contain entries created by “root”, the use of OR is not really necessary and is here just for demonstration purposes. Note that this is similar to the above example of author filter, the difference is that the author filter is a shortcut designed for convenience, while the term group can be used to filter on any property.
Facets allow you to see groupings based on similar or exact characteristics of a property. For example, you can see how many documents were created by each user or how many documents fall in a given creation date range.
Similar to filter, you can use term, numberRange and dateRange objects to specify the type of facet you require. Each facet allows you to specify field, whether it is disjunctive or not, and selections. The selection object varies depending on the type of facet. Here’s how term and date range facets look in a query. Note that date math expressions are fully supported.
{
jcr {
searches(siteKey: "digitall", language: "en", workspace: LIVE) {
search(...,
sortBy:{...},
filter:{...},
facets:{
term:[{field:"jcr:createdBy"}],
dateRange: [{field: "jcr:lastModified",
ranges: [{from: "now-1M", to: "now",
name: "last month"},
{from: "now-1y", to: "now",
name: "last year"}]}]
}) {
...
}
}
}
}
To correctly retrieve values for your facets, you must specify which value you want to resolve: TermValue or DateRangeValue.
facets {
field
data {
...on TermValue {
value
count
}
...on DateRangeValue {
range {
from
to
name
}
count
}
}
}
To filter on facets, you need to specify one or more selections in the selections list. For term facets, selections is a list of strings.
term:[{field:"jcr:createdBy" selections:["root"]}]
For range facets, it is an object describing the range.
dateRange: [{field: "jcr:lastModified",
ranges: [{from: "now-1M", to: "now", name: "last month"},
{from: "now-1y", to: "now", name: "last year"}]
selections:[{from: "now-1M", to: "now", name: "last month"}]}]
In this example, the set of results contains only the documents that were created by root and match the modified date criteria.
That’s it, full text search API is that simple.