GraphQL#

Comments supports accessing Comment objects via GraphQL. Be sure to read about Craft's GraphQL support (opens new window).

Comments#

Example#

{
    comments (ownerId: 2460, limit: 2, orderBy: "commentDate DESC") {
        commentDate @formatDateTime (format: "Y-m-d")
        name
        email
        comment
    }
}
{
    "data": {
        "comments": [
            {
                "commentDate": "2019-01-23",
                "name": "Test User",
                "email": "[email protected]",
                "comment": "Hey there, this is a great article, love your work!"
            },
            {
                "commentDate": "2019-01-23",
                "name": "John Smith",
                "email": "[email protected]",
                "comment": "Thanks, appreciate your comments! 😀"
            },
        ]
    }
}

The comments query#

This query is used to query for Comment objects. You can also use the singular comment to fetch a single node.

ArgumentTypeDescription
id[QueryArgument]Narrows the query results based on the elements’ IDs.
uid[String]Narrows the query results based on the elements’ UIDs.
status[String]Narrows the query results based on the elements’ statuses.
archivedBooleanNarrows the query results to only elements that have been archived.
trashedBooleanNarrows the query results to only elements that have been soft-deleted.
site[String]Determines which site(s) the elements should be queried in. Defaults to the current (requested) site.
siteId[QueryArgument]Determines which site(s) the elements should be queried in. Defaults to the current (requested) site.
uniqueBooleanDetermines whether only elements with unique IDs should be returned by the query.
preferSites[QueryArgument]Determines which site should be selected when querying multi-site elements.
enabledForSiteBooleanNarrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument.
searchStringNarrows the query results to only elements that match a search query.
relatedTo[QueryArgument]Narrows the query results to elements that relate to the provided element IDs. This argument is ignored, if relatedToAll is also used.
relatedToAssets[AssetCriteriaInput]Narrows the query results to elements that relate to an asset list defined with this argument.
relatedToEntries[EntryCriteriaInput]Narrows the query results to elements that relate to an entry list defined with this argument.
relatedToUsers[UserCriteriaInput]Narrows the query results to elements that relate to a use list defined with this argument.
relatedToCategories[CategoryCriteriaInput]Narrows the query results to elements that relate to a category list defined with this argument.
relatedToTags[TagCriteriaInput]Narrows the query results to elements that relate to a tag list defined with this argument.
relatedToAll[QueryArgument]Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. This argument is deprecated. relatedTo: ["and", ...ids] should be used instead.
fixedOrderBooleanCauses the query results to be returned in the order specified by the id argument.
inReverseBooleanCauses the query results to be returned in reverse order.
dateCreated[String]Narrows the query results based on the elements’ creation dates.
dateUpdated[String]Narrows the query results based on the elements’ last-updated dates.
offsetIntSets the offset for paginated results.
limitIntSets the limit for paginated results.
orderByStringSets the field the returned elements should be ordered by.
siteSettingsId[QueryArgument]Narrows the query results based on the unique identifier for an element-site relation.
withStructureBooleanExplicitly determines whether the query should join in the structure data.
structureIdIntDetermines which structure data should be joined into the query.
levelIntNarrows the query results based on the elements’ level within the structure.
hasDescendantsBooleanNarrows the query results based on whether the elements have any descendants in their structure.
ancestorOfIntNarrows the query results to only elements that are ancestors of another element in its structure, provided by its ID.
ancestorDistIntNarrows the query results to only elements that are up to a certain distance away from the element in its structure specified by ancestorOf.
descendantOfIntNarrows the query results to only elements that are descendants of another element in its structure provided by its ID.
descendantDistIntNarrows the query results to only elements that are up to a certain distance away from the element in its structure specified by descendantOf.
leavesBooleanNarrows the query results based on whether the elements are “leaves” in their structure (element with no descendants).
nextSiblingOfIntNarrows the query results to only the entry that comes immediately after another element in its structure, provided by its ID.
prevSiblingOfIntNarrows the query results to only the entry that comes immediately before another element in its structure, provided by its ID.
positionedAfterIntNarrows the query results to only entries that are positioned after another element in its structure, provided by its ID.
positionedBeforeIntNarrows the query results to only entries that are positioned before another element in its structure, provided by its ID.
ownerIdIntNarrows the query results based on the owner element the comment was made on, per the owners’ IDs.
commentDateStringNarrows the query results based on the comments’ commented date.
nameStringNarrows the query results based on the comments’ full name.
emailStringNarrows the query results based on the comments’ email.
commentStringNarrows the query results based on the comments’ actual comment text.

The CommentInterface interface#

This is the interface implemented by all comments.

FieldTypeDescription
idIDThe ID of the entity.
uidStringThe UID of the entity.
_countIntReturn a number of related elements for a field.
titleStringThe element’s title.
slugStringThe element’s slug.
uriStringThe element’s URI.
enabledBooleanWhether the element is enabled or not.
archivedBooleanWhether the element is archived or not.
siteIdIntThe ID of the site the element is associated with.
siteSettingsIdIDThe unique identifier for an element-site relation.
languageStringThe language of the site element is associated with.
searchScoreStringThe element’s search score, if the search parameter was used when querying for the element.
trashedBooleanWhether the element has been soft-deleted or not.
statusStringThe element’s status.
dateCreatedDateTimeThe date the element was created.
dateUpdatedDateTimeThe date the element was last updated.
lftIntThe element’s left position within its structure.
rgtIntThe element’s right position within its structure.
levelIntThe element’s level within its structure
rootIntThe element’s structure’s root ID.
structureIdIntThe element’s structure ID.
children[CommentInterface]The node’s children.
parentCommentInterfaceThe node’s parent.
prevCommentInterfaceReturns the previous element relative to this one, from a given set of criteria.
nextCommentInterfaceReturns the next element relative to this one, from a given set of criteria.
ownerIdIntThe ID of the element that owns the comment.
commentDateDateTimeThe comment's post date.
commentStringThe actual comment text.
nameStringThe full name for the comment’s author.
emailStringThe email for the comment’s author.
urlStringThe url the comment was made on.
votesIntThe number of total votes for this comment.
upvotesIntThe number of upvotes for this comment.
downvotesIntThe number of downvotes for this comment.
flagsIntThe number of flags for this comment.

The FlagInterface interface#

This is the interface implemented by all flags.

FieldTypeDescription
idIDThe ID of the entity.
sessionIdIDThe session ID from which the vote was submitted.
lastIpStringThe last known IP address of the voter.

The VoteInterface interface#

This is the interface implemented by all votes.

FieldTypeDescription
idIDThe ID of the entity.
sessionIdIDThe session ID from which the vote was submitted.
lastIpStringThe last known IP address of the voter.
upvoteBooleanWhether the vote is positive.
downvoteBooleanWhether the vote is negative.

Custom Fields#

If you’ve added custom fields to your Comments Form (Comments → Settings → Comments Form → Form Layout), you can query them by handle within a GraphQL fragment. If you added a summary Plain Text field, for example, your query might look like this:

{
    comments (ownerId: 2460, limit: 2, orderBy: "commentDate DESC") {
        commentDate @formatDateTime (format: "Y-m-d")
        name
        email
        comment
        ... on Comment {
            summary
        }
    }
}

Mutations#

createComment#

Saves a new nested visitor comment.

mutation NewComment($newParentId: ID, $ownerId: ID, $name: String, $email: String, $comment: String) {
    saveComment(newParentId: $newParentId, ownerId: $ownerId, name: $name, email: $email, comment: $comment) {
        id
        ownerId
        name
        email
        comment
    }
}

Query variables:

{
    "ownerId": 7,
    "newParentId": 30,
    "name": "Matt",
    "email": "[email protected]",
    "comment": "Here’s a nested comment."
}

saveComment#

Edit an existing comment.

mutation UpdateComment($id: ID, $comment: String) {
    saveComment(id: $id, comment: $comment) {
        id
        ownerId
        name
        email
        comment
    }
}

Query variables:

{
    "id": 34,
    "comment": "I’m totally changing what I said."
}

voteComment#

Upvote a comment:

mutation UpvoteComment($id: ID!, $upvote: Boolean) {
    voteComment(id: $id, upvote: $upvote) {
        id
        
        comment {
            flags
            upvotes
            downvotes
        }
    }
}

Query variables:

{
    "id": 34,
    "upvote": true
}

Downvote a comment:

mutation DownvoteComment($id: ID!, $downvote: Boolean) {
    voteComment(id: $id, downvote: $downvote) {
        id
        
        comment {
            flags
            upvotes
            downvotes
        }
    }
}

Query variables:

{
    "id": 34,
    "downvote": true
}

flagComment#

Flag a comment for moderation:

mutation FlagComment($id: ID!) {
    flagComment(id: $id) {
        id

        comment {
            flags
            upvotes
            downvotes
        }
    }
}

Query variables:

{
    "id": 34
}

subscribeComment#

Subscribe to an element’s comment notifications:

mutation SubscribeComment($ownerId: ID!) {
    subscribeComment(ownerId: $ownerId)
}

Repeat to toggle on/off.

Query variables:

{
    "ownerId": 34
}

Subscribe to a specific comment thread, where commentId is the beginning of that thread:

mutation SubscribeThread($ownerId: ID!, $commentId: ID) {
    subscribeComment(ownerId: $ownerId, commentId: $commentId)
}

Repeat to toggle on/off.

Query variables:

{
    "ownerId": 34,
    "commentId": 95
}

deleteComment#

Delete a comment:

mutation DeleteComment($id: ID!) {
    deleteComment(id: $id)
}

Query variables:

{
    "id": 34
}

Previous ← Events