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 to results 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.