The tags column stores one or more tag values, allowing you to categorize or group items by keywords across boards.

Via the API, the tags column supports read, filter, update, and clear operations.

Column Type	Implementation Type	Supported Operations
`tags`	`TagsValue`	Read: Yes Filter: Yes Update: Yes Clear: Yes

Queries

Tags columns can be queried through the column_values field on items queries using an inline fragment on TagsValue.

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

Fields

You can use the following fields to specify what information your TagsValue implementation will return.

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 assigned tags.
text `String`	The column's value as text. Returns `""` if the column has an empty value.
type `ColumnType!`	The column's type.
value `JSON`	The column's JSON-formatted raw value.

Filter

You can filter items by tag values using the items_page object. The tags column supports the following operators:

Operators	Compare Values
`any_of`	Tag IDs `-1` (blank values)
`not_any_of`	Tag IDs `-1` (blank values)
`is_empty`	`[]`
`is_not_empty`	`[]`

Examples

Filter items without tags

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

Filter out a specific tag (exclude tag ID 543210)

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

Mutations

Update

You can update a tags column using change_multiple_column_values by passing a JSON object in column_values.

Send the tag IDs in a tag_ids array.

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

Clear

You can clear a tags column using change_multiple_column_values by passing null or an empty object in column_values.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"tags\": null}"
  ) {
    id
  }
}