The rating column holds rating information for your item(s) which can be useful for ranking or assigning a grade to your item(s). The API allows you to read, filter, update, and clear the rating column.

Read a rating column

You can query the rating column using the column_values object that enables you to return column-specific subfields by sending a fragment in your query. Values for the rating column are of the RatingValue type.

query {
  items (ids:[1234567890, 9876543210]) {
    column_values {
      ... on RatingValue {
        rating
        updated_at
      }
    }
  }
}

Fields

Filter a rating column

Using the items_page object, you can easily filter a board's items by specific columns or column values. The table below contains the rating column's supported operators and compare values.

Examples

The following example returns all items on the specified board without a blank rating column.

query {
  boards(ids:1234567890) {
    items_page(
      query_params: {
        rules: {
          column_id: "rating"
          compare_value:[0]
          operator:not_any_of
        }
      }
	) {
      items {
        id
      }
    }
  }
}

Update a rating column

You can update a rating column using the change_multiple_column_values mutation and passing a JSON string in the column_values argument. Simple string updates are not supported.

JSON

To update a rating column using JSON, send a number between 1 and your rating scale. If you'd like to adjust your rating scale, you can do so in the column settings!

mutation {
  change_multiple_column_values(
    item_id:9876543210
    board_id:1234567890
    column_values: "{\"rating\" : {\"rating\" : 5}}"
	) {
    id
  }
}

Clear a rating column

You can also clear a rating column using the change_multiple_column_values mutation and passing null or an empty object in the column_values argument.

mutation {
  change_multiple_column_values(
    item_id:9876543210
    board_id:123456789
    column_values: "{\"rating\" : null}"
	) {
    id
  }
}