Writing a query
Once you have Augmented Search installed and running, you can start writing your first queries. To make it easier we recommend getting started with the GraphQL playground available in Jahia tools.
Please note that 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.
Getting started
As mentioned in other sections of this documentation, GraphQL supports introspection, and the best place to find documentation about Augmented Search API is in its schema, which is easily accessible on the right side of the GraphQL playground. This section of the documentation is focused on the public-facing search API, an administration API is also available under the "admin" node. You can find more details about its capabilities in the schema.
API Structure
The API structure is organized in layers, the (simple) example below fetches the displayableName
for all results matching the query string jahia
.
query {
search (q: "jahia"){
results {
hits {
displayableName
}
totalHits
}
}
}
This query can be broken down in the following layers:
- Level 1: The search node. This node takes a set of parameters to define a dataset to operate on (via children nodes).
- Level 2: An operation to perform on the dataset. In the above query,
results
is an operation to begin retrieving individual results from the dataset defined in level 1. - Level 3: An operation to perform on the results. In the above query,
hits
gives you access to individual results from the subset corresponding toresults
defined in level 2. - Level 4: The last layer gives you access to an individual field within the corresponding
hits
window.
This query will return the following:
{
"data": {
"search": {
"results": {
"hits": [
{
"displayableName": "Demo Roles and Users"
},
{
"displayableName": "Home"
}
]
"totalHits": 2
}
}
}
}
Since the query above uses default values, most parameters are hidden. But now that you understand the base structure, let's expose some of those parameters.
query {
search(
q: "jahia"
language: "en"
siteKeys: ["digitall"]
searchIn: CONTENT
workspace: LIVE
) {
results(
page: 0
size: 10
sortBy: { dir: ASC, field: "jcr:title.keyword" }
) {
hits {
displayableName
}
totalHits
}
}
}
This query makes it more obvious what data is being requested, remember:
- The
search
node defines the dataset - The
results
node operates on that defined dataset. In this example returning a subset of the dataset (this technique is usually used for paginating through results).
Finally, let's perform one last operation on the dataset by introducing an aggregation.
query {
search(
q: "jahia"
language: "en"
siteKeys: ["digitall"]
searchIn: CONTENT
workspace: LIVE
) {
results(
page: 0
size: 10
sortBy: { dir: ASC, field: "jcr:title.keyword" }
) {
hits {
displayableName
}
totalHits
}
termFacet(field: "jgql:createdBy") {
data {
value
count
}
}
}
}
In the above query, the termFacet
aggregation will return the number of documents by author, within the dataset defined in the search
node.
Query fields
Some of the GraphQL nodes will take a field
parameter (facets, sorting, filters), this field comes directly from your Elasticsearch mapping, which itself is derived from the data model of your Jahia site.
There are multiple ways for you to identify fields available for querying:
- The first technique is by knowing your Jahia data model, since the Elasticsearch mapping is automatically derived from it.
- Another technique consists of either retrieving the mapping or fetching documents directly from Elasticsearch during your development phase.