In API version 2023-10, the complexity of the text field for mirror, dependency, and connect boards columns has increased when using the new typed column values.

Check out the before and after connect board column examples below to see this update in action!

Please note that the exact complexity cost will be decided in the near future. The values depicted in the examples below are not the final complexity costs.

Before

Sample query

query {
  items (ids:1234567890) {
    column_values (ids: "connect_boards") {
        text
    }
  }
  complexity {
    query
  }
}

Sample response

{
  "data": {
    "items": [],
    "complexity": {
      "query": 21
    }
  },
  "account_id": 12345678
}

After

Sample query

query {
  items (ids:1234567890) {
    column_values {
      ... on BoardRelationValue {
        text
      }
    }
  }
  complexity {
    query
  }
}

Sample response

{
  "data": {
    "items": [],
    "complexity": {
      "query": 30
    }
  },
  "account_id": 12345678
}

API version 2023-10 contains a major update to the column values object, or what we like to call, column values v2. The object itself remains the same, but we introduced new fields that allow for more simple, intuitive, and expressive filtering. The five core fields include:

FieldDescription
column Column!The column the value belongs to.
id ID!The column's unique identifier.
text StringThe text representation of the column's value. Not every column supports the text value.
type ColumnType!The column's type.
value JSONThe column's raw value.

On top of the new fields, we added implementations that enable you to query subfields for a specific column type using GraphQL fragments, or queries that will only run if a specific type is returned. Each column is of a different type, so they all have unique fields to return data specific to that column.

Let's take a look at the LocationValue type that you can use to return location column-specific fields in your query. In addition to the five core fields mentioned above, you can also return the address, city, city_short, country, country_short, lat, lng, place_id, street, street_number, street_number_short, street_short, and updated_at fields.

Sample query

query {
  items (ids:[1234567890, 9876543210]) {
    column_values {
      ... on LocationValue {
        country
        street
        street_number
      }
    }
  }
}

The type field on columns queries will change from a string to ColumnType! in API version 2023-10. The columns field on boards queries, which takes the types argument, will also change from a string to [ColumnType!].

This update also impacts the output value for specific columns. In API version 2023-07, the type of each column was inconsistent in read and write operations. To align this behavior, the API will now return an enum value that better matches the input value in 2023-10.

Column titleInput value (2023-07 and before)Output value (2023-07 and before)Enum value (2023-10 and later)
Auto numberauto_numberautonumberauto_number
Buttonbuttonbuttonbutton
Checkboxcheckboxbooleancheckbox
Color pickercolor_pickercolor-pickercolor_picker
Connect boardsboard-relationboard-relationboard_relation
Countrycountrycountrycountry
Creation logcreation_logpulse-logcreation_log
Datedatedatedate
Dependencydependent_ondependencydependency
Dropdowndropdowndropdowndropdown
Emailemailemailemail
Filesfilesfilefile
Formulaformulaformulaformula
Hourhourhourhour
Item IDitem_idpulse-iditem_id
Last updatedlast_updatedpulse-updatedlast_updated
Linklinklinklink
Locationlocationlocationlocation
Long textlong_textlong-textlong_text
Mirrormirrorlookupmirror
monday docmonday_docdocdoc
Namenamenamename
Numbersnumbersnumericnumbers
Peoplepeoplemultiple-personpeople
Phonephonephonephone
Progress trackingprogresscolumns-batteryprogress
Ratingratingratingrating
Statusstatuscolorstatus
Tagstagstagtags
Texttexttexttext
Timelinetimelinetimerangetimeline
Time trackingtime_trackingdurationtime_tracking
Votevotevotesvote
Weekweekweekweek
World clockworld_clocktimezoneworld_clock

The deprecated items_by_column_values and items_by_multiple_column_values objects will be removed and replaced with the new items_page_by_column_values object in API version 2023-10.

The new object provides a simple and intuitive way to query an item's column values. It combines two old objects into one while simultaneously keeping the behaviors nearly the same. It utilizes string values per column to search and return items with specific values, as well as cursor-based pagination to filter through large data sets.

It supports limited column types, but we will gradually add support for additional types over time. Certain columns also have restrictions that impact the scope of the object's querying abilities.

The items_page_by_column_values object enables you to query simple values and works best for simple use cases. We also added the new items_page object that has very powerful filtering capabilities and can be used for your advanced filtering needs!

In API version 2023-10, many of the ID arguments and fields that were integers have become ID type. This includes, but is not limited to, board_id, item_id, parent_item_id, parent_id, team_id, id, update_id, workspace_id, user_id, ids, and doc_folder_id.

The type ID is alphanumeric and accepts both strings and integers as valid inputs, but it will only return strings. Though it accepts both, we advise against treating them as integers and storing them in your database as text.

Let's take the docs object for example. The tables below show the impacted arguments and fields, what type they were before the update, and what they look like after the update.

Fields that are changing from Int to ID

ObjectField
Accountid
AccountProductid
Boardboard_folder_id
Boardworkspace_id
Documentdoc_folder_id
Documentid
Documentobject_id
Documentworkspace_id
DocumentBlockdoc_id
Folderid
Folderowner_id
Tagid
Teamid
Userid
Webhookboard_id
Workspaceid

Impacted arguments

BeforeAfter
ids [Int]ids [ID!]
object_ids [Int]object_ids [ID!]
workspace_ids [Int]workspace_ids [ID]

In API version 2023-10, you can no longer send empty parentheses in queries. If you try, the query will return an error. Check out the code sample below to see a query that was previously supported and find out how you can update it so it won't throw an error!

Previously supported sample query

query {
  boards () {
    id
  }
}

Updated sample query

query {
  boards (ids:1234567890) {
    id
  }
}
query {
  boards (limit:10) {
    id
  }
}

Strings must be sent with quotation marks, so you can no longer send arguments without them in API versions 2023-10 and later. If you send strings without quotation marks, it will result in an error.

Check out the code samples below to see queries and mutations that were previously supported, and find out how you can update them so they won't throw an error!

Previously supported code samples

mutation {
  create_column(board_id: 1234567890, title:Country, description: "This is my country column", column_type:country) {
    id
    title
    description
  }
}
query {
  users (name: Test) {
    id
  }
}
query {
  items (ids: 1231234123) {
    column_values (ids: task_status) {
      value
    }
  }
}

Updated code samples

mutation{
  create_column(board_id: 1234567890, title:"Country", description: "This is my country column", column_type:country) {
    id
    title
    description
  }
}
query {
  users (name: "Test") {
    id
  }
}
query {
  items (ids: 1231234123) {
    column_values (ids: "task_status") {
      value
    }
  }
}

The newest_first argument for boards queries will be deprecated in API version 2023-10. You can instead use the order_by argument and sort by the creation date, so the most recently created boards will be listed first.

Sample query

query {
  boards (ids: 1234567890, order_by: created_at) {
    id
  }
}