---

Kolumna ocen przechowuje wartość liczbową, której można używać do ustalania rankingu lub oceny elementów. Korzysta z typu kolumny rating i zwraca wartości jako RatingValue w schemacie GraphQL.

Za pomocą API możesz odczytywać i filtrować wartości w kolumnie ocen, a także tworzyć, aktualizować i czyścić tę kolumnę.

Typ kolumny	Typ implementacji	Obsługiwane operacje
rating	RatingValue	Odczyt: tak Filtrowanie: tak Tworzenie: tak Aktualizowanie: tak Czyszczenie: tak

---

Zapytania

Możesz pobierać wartości z kolumn ocen za pomocą pola column_values w zapytaniach items, używając wbudowanego fragmentu typu RatingValue.

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

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on RatingValue {
          id
          rating
          text
          value
          updated_at
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890, 9876543210] };

const response = await mondayApiClient.request(query, variables);

Pola

Za pomocą poniższych pól możesz określić, jakie informacje zwróci implementacja RatingValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
id ID!	Unikalny identyfikator kolumny.
rating Int	Liczbowa wartość oceny (np. 1–5). Zwraca null, jeśli kolumna nie zawiera wartości.
text String	Wartość oceny w postaci ciągu znaków (np. "5"). Zwraca "", jeśli kolumna nie zawiera wartości.
type ColumnType!	Typ kolumny (rating).
updated_at Date	Data ostatniej aktualizacji oceny.
value JSON	Surowa wartość kolumny w postaci ciągu JSON. Zawiera {"rating": N}, gdzie N to liczbowa wartość oceny, lub null.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Feature A",
        "column_values": [
          {
            "id": "rating",
            "rating": 4,
            "text": "4",
            "value": "{\"rating\":4}",
            "updated_at": "2026-03-20T12:00:00Z"
          }
        ]
      },
      {
        "name": "Feature B",
        "column_values": [
          {
            "id": "rating",
            "rating": null,
            "text": "",
            "value": null,
            "updated_at": null
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

Możesz filtrować elementy według wartości ocen za pomocą obiektu items_page. Kolumna ocen obsługuje następujące operatory:

Operator	Wartość porównawcza	Opis
any_of	Tablica wartości ocen: 0 (pusta), 1, 2, 3, 4, 5	Zwraca elementy z dowolną z podanych ocen. Użyj 0, aby uwzględnić puste wartości.
not_any_of	Tablica wartości ocen: 0 (pusta), 1, 2, 3, 4, 5	Wyklucza elementy z dowolną z podanych ocen. Użyj 0, aby wykluczyć puste wartości.

Przykłady

Filtrowanie według konkretnej oceny

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "rating"
            compare_value: [5]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on RatingValue {
            rating
          }
        }
      }
    }
  }
}

Filtrowanie według niepustych ocen

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

---

Mutacje

Tworzenie

Możesz utworzyć kolumnę ocen za pomocą mutacji create_column, ustawiając column_type na rating. Opcjonalnie możesz skonfigurować skalę ocen, symbol i kolor za pomocą argumentu defaults.

mutation {
  create_column(
    board_id: 1234567890
    title: "Priority Score"
    column_type: rating
    defaults: "{\"settings\": {\"limit\": 10, \"symbol\": \"stars\", \"color\": \"#fdab3d\"}}"
  ) {
    id
    title
    settings
  }
}

Argument defaults przyjmuje ciąg JSON zawierający obiekt settings z następującymi opcjonalnymi polami:

Pole	Typ	Opis
limit	integer	Maksymalna wartość oceny. Musi mieścić się w zakresie od 3 do 10. Domyślnie wynosi 5.
symbol	string	Typ symbolu oceny. Dozwolone wartości: "stars", "hearts". Domyślnie: "stars".
color	string	Kod koloru w formacie szesnastkowym wyświetlanej oceny (np. "#fdab3d"). Musi mieć dokładnie 7 znaków, łącznie z #.

Aktualizowanie

Możesz zaktualizować kolumnę ocen za pomocą change_simple_column_value lub change_multiple_column_values.

change_simple_column_value

Przekaż ocenę jako ciąg znaków.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "rating"
    value: "5"
  ) {
    id
    name
  }
}

change_multiple_column_values

Przekaż obiekt JSON z wartością rating jako liczbą z zakresu od 1 do limitu skonfigurowanego dla kolumny.

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

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      board_id: $boardId
      item_id: $itemId
      column_values: $columnValues
    ) {
      id
      name
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    rating: { rating: 5 }
  })
};

const response = await mondayApiClient.request(query, variables);

Ustawianie oceny podczas tworzenia elementu

Możesz ustawić ocenę podczas tworzenia elementu, przekazując wartość kolumny ocen w argumencie column_values.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New feature"
    column_values: "{\"rating\": {\"rating\": 3}}"
  ) {
    id
    name
  }
}

Czyszczenie

Możesz wyczyścić kolumnę ocen za pomocą change_simple_column_value lub change_multiple_column_values.

change_simple_column_value

Przekaż pusty ciąg znaków.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "rating"
    value: ""
  ) {
    id
    name
  }
}

change_multiple_column_values

Przekaż null lub pusty obiekt.

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

---

Odczytywanie konfiguracji kolumny

Możesz odczytać konfigurację kolumny ocen, pobierając pole settings obiektu columns. Zwrócony obiekt JSON zawiera ustawienia kolumny.

query {
  boards(ids: 1234567890) {
    columns(ids: ["rating"]) {
      id
      title
      settings
    }
  }
}

Przykładowa odpowiedź settings

Obiekt settings zawiera:

{
  "limit": 5,
  "symbol": "stars",
  "color": "#fdab3d"
}

Pole	Typ	Opis
limit	integer	Maksymalna wartość oceny (od 3 do 10). Domyślnie 5.
symbol	string	Typ symbolu oceny: "stars" lub "hearts".
color	string	Kod koloru w formacie szesnastkowym wyświetlanej oceny (np. "#fdab3d").

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny ocen za pomocą zapytania get_column_type_schema. Zwraca ono strukturę, reguły walidacji i dostępne właściwości konfiguracji kolumny.

query {
  get_column_type_schema(
    type: rating
  )
}

{
  "data": {
    "get_column_type_schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "settings": {
            "type": "object",
            "description": "Column specific settings",
            "properties": {
              "limit": {
                "type": "integer",
                "description": "Maximum rating value",
                "minimum": 3,
                "maximum": 10
              },
              "symbol": {
                "type": "string",
                "description": "Rating symbol type",
                "enum": [
                  "stars",
                  "hearts"
                ]
              },
              "color": {
                "type": "string",
                "description": "Hex color code for the rating display",
                "minLength": 7,
                "maxLength": 7
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

Odpowiedź zawiera nazwy właściwości, ich typy, ograniczenia (takie jak maksymalna długość i dozwolone wartości) oraz opisy poszczególnych ustawień. Możesz użyć jej do walidacji ustawień kolumny, dynamicznego generowania interfejsów lub przekazywania kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.