Querying Documentation | JT Development

Querying Entries with Engagement

Engagement lets you query entries by Rating, Likes/Dislikes, and Favorites metrics directly from your field handle on an element query. This keeps queries Craft-native and easy to compose with other entry filters.

Basic pattern:

{% set results = craft.entries()
  .myFieldHandle({
    /* criteria */
  })
  .all() %}

How It Works

Each Engagement field handle accepts a criteria object. You can combine Engagement criteria with normal Craft query methods like section, site, orderBy, limit, and relatedTo.

{% set entries = craft.entries()
  .section('articles')
  .myRatingField({
    minAverage: 4,
    minVoteCount: 10
  })
  .limit(12)
  .all() %}

Shared Criteria (All Engagement Fields)

Key	Type	Description
enabled	boolean	Filters by the effective enabled state for that field on each entry.
siteId	int	Filters metrics using a specific site context.

Rating Criteria Keys

Key	Type	Description
minAverage	number	Minimum average rating.
maxAverage	number	Maximum average rating.
minVoteCount	int	Minimum number of rating votes.
maxVoteCount	int	Maximum number of rating votes.
hasVotes	boolean	true = voteCount > 0, false = voteCount = 0.

{% set topRated = craft.entries()
  .myRatingField({
    minAverage: 4.2,
    minVoteCount: 25,
    hasVotes: true
  })
  .all() %}

Likes/Dislikes Criteria Keys

Key	Type	Description
minLikes	int	Minimum like count.
maxLikes	int	Maximum like count.
minDislikes	int	Minimum dislike count.
maxDislikes	int	Maximum dislike count.
minTotalVotes	int	Minimum total votes (likes + dislikes).
maxTotalVotes	int	Maximum total votes (likes + dislikes).
totalVotes	int	Exact total votes shorthand.
minScore	int	Minimum score (likes - dislikes).
maxScore	int	Maximum score (likes - dislikes).
score	int	Exact score shorthand.

{% set controversial = craft.entries()
  .myLikesField({
    minLikes: 20,
    minDislikes: 20,
    minTotalVotes: 50
  })
  .all() %}

{% set highlyPositive = craft.entries()
  .myLikesField({
    minTotalVotes: 30,
    minScore: 20
  })
  .all() %}

Favorites Criteria Keys

Key	Type	Description
minFavorites	int	Minimum favorite count.
maxFavorites	int	Maximum favorite count.
hasFavorites	boolean	true = favoriteCount > 0, false = favoriteCount = 0.

{% set mostSaved = craft.entries()
  .myFavoritesField({
    minFavorites: 15,
    hasFavorites: true
  })
  .all() %}

Sorting by Engagement Metrics

Use orderBy() with field-handle sort tokens:

ratings: <handle>__average, <handle>__voteCount

likes: <handle>__likes, <handle>__dislikes, <handle>__score, <handle>__totalVotes

favorites: <handle>__count

{% set trending = craft.entries()
  .section('news')
  .myRatingField({ minVoteCount: 10 })
  .orderBy('myRatingField__average desc, postDate desc')
  .all() %}

{% set mostLiked = craft.entries()
  .myLikesField({ minTotalVotes: 25 })
  .orderBy('myLikesField__score desc')
  .all() %}

{% set mostFavorited = craft.entries()
  .myFavoritesField({ hasFavorites: true })
  .orderBy('myFavoritesField__count desc')
  .all() %}