GraphQL documentation for the dotCMS Content Management System

GraphQL is a query language for APIs for runtime queries with existing data. First implemented in the dotCMS 5.1 version, content can be fetched via the GraphQL content delivery API. The GraphQL content delivery API has a number of advantages over REST:

  • One single endpoint: api/v1/graphql
  • Self documenting via schema introspection
  • No over fetching of data
  • No need for multiple requests for getting desired data
  • Client decides exactly what data wants

The following documentation illustrates how to access the GraphQL content delivery API:

How to Query

To test dotCMS's GraphQL API is recommended to use a GraphQL-aware client like Insomnia or Altair

The entire delivery GraphQL API has a single endpoint: /api/v1/graphql

Authentication

The GraphQL API accepts the same options of authentication supported by our REST API.

See https://dotcms.com/docs/latest/rest-api-authentication#Methods

Querying

Queries can be made following three approaches:

  • Using Collections root fields
  • Using Search root field
  • Any combination of the above

Root fields are fields available at the root of the GraphQL request body

{
    rootField1
    rootField2
       .
       .
       .
    rootFieldN
{

In dotCMS' GraphQL implementation, the root fields are all Collections and the Search field.

Arguments

Arguments are a way to filter the results of root fields. They are specified inside parentheses following the root field name and are separated by comma: rootField(arg1:value, arg2:123)

The available arguments for all Collections and the Search root fields are:

  • query : lucene query - String (mandatory for the Search root field)
  • limit : limits the number of items in the result - Integer (if not specified, results are limited to 100)
  • offset : offsets the items in the result - Integer
  • sortBy : sorts by varname of a sortable field - String

Collections

The Content Delivery GraphQL Implementation has all dotCMS contentTypes and baseTypes available as collections root fields, following the naming convention {contentTypeVarName}Collection and {baseTypeName}BaseTypeCollection.

They can be combined in the same query, meaning, including multiple collections.

Example usage - single collection

{
  commentsCollection(limit: 10) {
    title
    author
  }
}

Printing the GraphQL Schema

The GraphQL Schema can be printed for debugging purposes by including PRINT_GRAPHQL_SCHEMA=true in the dotmarketing-config.properties. This change should be made in a configuration plugin.

Example dotmarketing-config.properties property

PRINT_GRAPHQL_SCHEMA=true

General Search

In addition to querying collections of contentTypes or baseTypes, you can query, in a combined way, all content of dotCMS, using the search root field and use inline fragments to fetch data specific to a contentType or baseType

Example usage

{
  search(query: "title:News", limit: 10) {

    title
    modDate
    modUser {
      firstName
      lastName
    }

    ...on htmlpageasset {
      url
      showOnMenu
      cachettl
      friendlyname
      seokeywords
      pagemetadata
    }

    ...on SimpleWidget {
      widgetCode
    }

   ...on FileBaseType {
      fileName
      description
      fileAsset {
        versionPath
          idPath
          name
      }
      metaData {
        key
        value
      }


          }
  }
}

Inline Fragments

... on {contentTypeOrBaseTypeVarname} {
     {field1VarName}
     {field2VarName}
       .
       .
       . 
     {fieldNVarName}
}

Example usage - Searching all content with News on its title, and fetching specific fields for content of type Htmlpage and Widget:

{
  search(query: "title:News", limit: 10) {

    title
    modDate
    modUser {
      firstName
      lastName
    }

    ...on htmlpageasset {
      url
      template
      showOnMenu
      sortOrder
      cachettl
      friendlyname
      redirecturl
      httpsreq
      seodescription
      seokeywords
      pagemetadata
    }

    ...on Widget {
      widgetCode
    }

  }
}

Types and Fields

There are various content structures or Types in the system and how they can be accessed via graphQL. The documentation below defines all the different Types in the system and the various system or custom fields that are or can be associated with each Type

Root Type - Contentlet (only for the search root field)

If you use the search root field, the resulting items will be of type Contentlet.

The Contentlet root type has a number of fields available for all content in dotCMS, regardless of its baseType or contentType

Field NameField Type
modDateString
titleString
titleImageBinary*
contentTypeString (type var name)
baseTypeString (base type name)
liveBoolean
workingBoolean
archivedBoolean
lockedBoolean
conLanguageLanguage*
identifierString
inodeString
folderFolder*
hostSite*
ownerUser*
modUserUser*

*GraphQL Custom Type: Please check available field names and types in Custom Types section.

Base Types

Base types make possible to fetch common fields in all Content Types created off the Base Type.

They are available as Collections or using Inline fragments when using the search root field

FileBaseType - (groups all dotCMS content types of base type File)

Field NameField Type
fileNameString
descriptionString
fileAssetBinary*
metaDataKeyValue*
showOnMenu[String]
sortOrderInteger

*GraphQL Custom Type: Please check available field names and types in Custom Types section.

PageBaseType - (groups all dotCMS content types of base type Page)

Field NameField Type
urlString
templateString (identifier of the template)
showOnMenu[String]
sortOrderInteger
cachettlString
friendlynameString
redirecturlString
httpsreq[String]
seodescriptionString
seokeywordsString
pagemetadataString

PersonaBaseType - (groups all dotCMS content types of base type Persona)

Field NameField Type
nameString
keyTagString
photoBinary*
tags[String]
descriptionString

*GraphQL Custom Type: Please check available field names and types in Custom Types section.

WidgetBaseType (groups all dotCMS content types of base type Widget)

Field NameField Type
widgetTitleString
widgetCodeString
widgetUsageString
widgetPreexecuteString

VanityURLBaseType (groups all dotCMS content types of base type Vanity URL)

Field NameField Type
urlString
forwardToString
actionString
orderInteger

KeyValueBaseType (groups all dotCMS content types of base type Key/Value)

Field NameField Type
keyString
valueString

FormBaseType (groups all content types of base type Form)

Field NameField Type
formTitleString
formEmailString
formReturnPageString

Content Types

Every single Content Type defined in dotCMS is available as a GraphQL Type. The available fields are all fields defined on the ContentType. The mapping between dotCMS field types and GraphQL types is presented in the following table:

dotCMS TypeGraphQL Type
BinaryBinary
CategoryCategory
Image / FileFileasset
RelationshipsFieldType pointing to. (Single element or list depending on the cardinality)
Key/ValueKeyValue
Site or FolderSiteOrFolder
OtherString

Custom Types

Represent non-escalar dotCMS field types as GraphQL Types

Binary

Represents a dotCMS field of type Binary

Field NameField Type
versionPathString
idPathString
nameString
sizeLong
mimeString
isImageBoolean

Category

Represents a dotCMS field of type Category

Field NameField Type
inodeString
activeBoolean
nameString
keyString
keywordsString
velocityVarString

SiteOrFolder

Represents a dotCMS field of type Site or Folder

Field NameField Type
folderIdString
folderFileMaskString
folderSortOrderInteger
folderNameString
folderPathString
folderTitleString
folderDefaultFileTypeString
hostIdString
hostNameString
hostAliasesString
hostTagStorageString

KeyValue

Represents a dotCMS field of type Key/Value

Field NameField Type
keyString
valueString

Additional Custom Types

These ones do not correspond to dotCMS field types but are non-escalars fields available in the Contentlet Interface

Site

Field NameField Type
hostIdString
hostNameString
hostAliasesString
hostTagStorageString

Folder

Field NameField Type
folderIdString
folderFileMaskString
folderSortOrderInteger
folderNameString
folderPathString
folderTitleString
folderDefaultFileTypeString (Identifier of the contentType)

Language

Field NameField Type
idInteger
languageCodeString
countryCodeString
languageString
countryString

User

Field NameField Type
userIdString
firstNameString
lastNameString
emailString

Generated Types

These are GraphQL Types generated from all dotCMS Content Type definitions present at the moment of the generation. Any change to a Content Type or its fields (create, update, delete) will force all types being regenerated.

The following table shows the mapping between dotCMS field types and GraphQL Types

dotCMS TypeGraphQL Type
BinaryBinary
CategoryList of Binary
ImageFileasset
FileFileasset
DateTimeDateTime
TimeTime
KeyValueList of Key_value
CheckboxList of String
MultiselectList of String
TagList of String
HostOrFolderSiteOrFolder
OthersString