Elasticsearch REST API

dotCMS supports pulling Content from Elasticsearch using the REST API. This document explains the API endpoints and options, and provides several examples of how to perform Elasticsearch queries using the REST API.

Endpoints

There are two endpoints to the Elasticsearch REST API:

Options

Display Live vs. Working Content (live Parameter)

By default, only live (published) content is returned. To return working versions of content, you may add the URL parameter live=false to the request.

curl -H "Content-Type: application/json" -XPOST http://localhost:8082/api/es/search?live=false -d '{...

Note:

• The /es/ endpoints, consistent with Content API retrieval, will only return working (unpublished) content for authenticated back-end users.
  • Unauthenticated users may still use the endpoints, but when they do the endpoints will return only live content (and if the live=false parameter is supplied, it will be ignored).
• You may set the live parameter to true or false.
  • However since live=true is the default, explicitly adding this parameter produces the same results as if the live parameter had not been included.

Display Related Content (depth Parameter)

By default, only the properties of the content which matches the query is returned. You may also include content by including the depth parameter, as follows:

curl -H "Content-Type: application/json" -XPOST http://localhost:8082/api/es/search?depth=2 -d '{...

The depth parameter can be any of the following:

Easily Readable Results (Pretty Print)

By default, the value returned from an Elasticsearch REST query will be displayed in an unformatted block (without additional spaces and carriage returns to make it easily human readable). To display the results in a more easily readable format, append ?pretty to the end of the URL. For example:

curl -H "Content-Type: application/json" -XPOST http://localhost:8082/api/es/search?pretty -d '{...

Examples

Basic Content Search

The following curl command searches for the word “gas” in any field using the “catchall” keyword to search within all fields.

curl -H "Content-Type: application/json" -XPOST http://localhost:8082/api/es/search -d '
    {
        "query": {
            "bool": {
                "must": {
                    "term": {
                        "catchall": "gas"
                    }
                }
            }
        }
    }'

For more information on searching within all fields, please see the Search Within all Content Fields documentation.

Lucene Query

The following command performs a query using the Lucene syntax and displays it using the pretty print option.

curl -H "Content-Type: application/json" -XPOST https://demo.dotcms.com/api/es/search?pretty -d '
{
    "query" : { 
        "query_string" : {
            "query" : "+contentType:webPageContent +webPageContent.title:about*"
        } 

    },
    "size":3 ,
    "sort":{
        "moddate":"asc"
    }
}'

This enables you to use the simpler, compact Lucene syntax for the core query, while also using additional Elasticsearch terms and modifiers via the full JSON syntax (including sorting and limiting the number of results, as in this example).

Aggregations Query

The following curl command performs an aggregations query using the raw results endpoint:

curl -H "Content-Type: application/json" -XPOST http://localhost:8082/api/es/raw -d '
    {
        "query" : { "query_string" : {"query" : "gas*"} },
        "aggs" : {
            "tags" : { "terms" : {"field" : "news.tags"} }
        }
    }'

For more information on aggregation queries, please see the Elasticsearch Aggregations documentation.

Date Histogram

If you are looking for summary data based on a content object's date propery, you can use elasticsearch's date_histogram function. This example will give you a summary of blog posts by month.

curl -H "Content-Type: application/json" -H "Authorization:Bearer xxx" -XPOST http://localhost:8082/api/es/search -d '
{  
    "query" : 
    { 
        "query_string" : 
        {
            "query" : "+contenttype:blog +blog.postingDate:[2020-01-01 TO 2029-01-01]"
        } 
    },
 "size":0,
 "aggs":{  
     "metrics_by_day":{  
     "date_histogram":{  
        "field":"blog.postingDate",
        "calendar_interval": "month"

     }
   }
 }
}
'

You can learn more about elasticsearch's date histogram functions here: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html

Suggestions

The following curl performs a search to support a Suggestions feature (Did you mean?), using the raw results endpoint:

curl -H "Content-Type: application/json" -XPOST http://localhost:8082/api/es/raw -d '
    {
      "suggest" : {
        "title-suggestions" : {
          "text" : "gs pric rollrcoater",
          "term" : {
            "size" : 3,
            "field" : "title"
          }
        }
      }
    }'

For more information on implementing features such as suggestions, please see the Elasticsearch API documentation.