The tags column holds words and/or phrases that help you group your items using these keywords. The API allows you to read, filter, update, and clear the tags column.

Read a tags column

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

query {
  items (ids:[1234567890, 9876543210]) {
    column_values {
      ... on TagsValue {
        tag_ids
        text
      }
    }
  }
}

Fields

Field	Description
column `Column!`	The column the value belongs to.
id `ID!`	The column's unique identifier.
tag_ids `[Int!]!`	The unique identifiers of the column's tags.
text `String`	The column's value as text. This field will return `""` if the column has an empty value.
type `ColumnType!`	The column's type.
value `JSON`	The column's JSON-formatted raw value.

Filter a tags 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 tags column's supported operators and compare values.

Operators	Compare Values
`any_of`	The tag IDs to filter by `-1` (blank values)
`not_any_of`	The tag IDs to filter by `-1` (blank values)
`is_empty`	`[]`
`is_not_empty`	`[]`

Examples

The following example returns all items on the specified board without tags.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "tags"
            compare_value: [-1]
            operator:any_of
          }
        ]
      }
		) {
      items {
        id
        name
      }
    }
  }
}

Here's another example that filters out a single tag and only returns items on the specified board that don't have tag 543210.

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

Update a tags column

You can update a tags 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 tags column, send the tag IDs in an array.

mutation {
  change_multiple_column_values(
    item_id:9876543210
    board_id:1234567890
    column_values: "{\"tags\" : {\"tag_ids\" : [\"295026\", \"295064\"]}}"
	) {
    id
  }
}

Clear a tags column

You can also clear a tags 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:1234567890
    column_values: "{\"tags\" : null}"
	) {
    id
  }
}