Aggregations#

Every record type has an aggregation query: {collectionName}Aggregated. For example, aggregate fm.teal.alpha.feed.play records with fmTealAlphaFeedPlayAggregated.

Aggregation queries are public; no authentication required.

Basic Aggregation#

Group by a field to count occurrences:

query {
  fmTealAlphaFeedPlayAggregated(groupBy: [{ field: artists }]) {
    artists
    count
  }
}

{
  "data": {
    "fmTealAlphaFeedPlayAggregated": [
      { "artists": [{ "artistName": "Radiohead" }], "count": 142 },
      { "artists": [{ "artistName": "Boards of Canada" }], "count": 87 }
    ]
  }
}

Filtering & Sorting#

Use where to filter records, orderBy to sort by count, and limit to cap results.

Get a user's top 10 artists for 2025:

query {
  fmTealAlphaFeedPlayAggregated(
    groupBy: [{ field: artists }]
    where: {
      actorHandle: { eq: "baileytownsend.dev" }
      playedTime: { gte: "2025-01-01T00:00:00Z", lt: "2026-01-01T00:00:00Z" }
    }
    orderBy: { count: DESC }
    limit: 10
  ) {
    artists
    count
  }
}

{
  "data": {
    "fmTealAlphaFeedPlayAggregated": [
      { "artists": [{ "artistName": "Radiohead" }], "count": 142 },
      { "artists": [{ "artistName": "Boards of Canada" }], "count": 87 }
    ]
  }
}

Multiple Fields#

Group by multiple fields. Get top tracks with their artists:

query {
  fmTealAlphaFeedPlayAggregated(
    groupBy: [{ field: trackName }, { field: artists }]
    where: {
      actorHandle: { eq: "baileytownsend.dev" }
      playedTime: { gte: "2025-01-01T00:00:00Z", lt: "2026-01-01T00:00:00Z" }
    }
    orderBy: { count: DESC }
    limit: 10
  ) {
    trackName
    artists
    count
  }
}

{
  "data": {
    "fmTealAlphaFeedPlayAggregated": [
      { "trackName": "Everything In Its Right Place", "artists": [{ "artistName": "Radiohead" }], "count": 23 },
      { "trackName": "Roygbiv", "artists": [{ "artistName": "Boards of Canada" }], "count": 18 }
    ]
  }
}

Date Truncation#

Group datetime fields by time intervals: HOUR, DAY, WEEK, or MONTH.

Get plays per month:

query {
  fmTealAlphaFeedPlayAggregated(
    groupBy: [{ field: playedTime, interval: MONTH }]
    where: {
      actorHandle: { eq: "baileytownsend.dev" }
      playedTime: { gte: "2025-01-01T00:00:00Z", lt: "2026-01-01T00:00:00Z" }
    }
    orderBy: { count: DESC }
  ) {
    playedTime
    count
  }
}

{
  "data": {
    "fmTealAlphaFeedPlayAggregated": [
      { "playedTime": "2025-03-01", "count": 847 },
      { "playedTime": "2025-01-01", "count": 623 },
      { "playedTime": "2025-02-01", "count": 598 }
    ]
  }
}

Reference#

Query Structure#

• {collectionName}Aggregated - Aggregation query for any record type
• groupBy (required) - Array of fields to group by, with optional interval for datetime fields
• where (optional) - Filter conditions
• orderBy (optional) - Sort by count (ASC or DESC)
• limit (optional) - Maximum groups to return (default: 100)

Available Columns#

Beyond record fields, group by: uri, cid, did, collection, indexedAt, actorHandle

Validation#

• Date intervals can only be applied to datetime fields
• Maximum 5 groupBy fields per query