Kolumna liczb przechowuje wartości liczbowe (zmiennoprzecinkowe lub całkowite) i może opcjonalnie zawierać symbol jednostki (np. $, % lub własny ciąg znaków). Jest często używana do budżetów, wyników, ilości i innych mierzalnych danych.

Za pomocą API kolumna liczb obsługuje odczytywanie, filtrowanie, aktualizowanie i czyszczenie wartości.

Typ kolumny	Typ implementacji	Obsługiwane operacje
numbers	NumbersValue	Odczyt: Tak Filtrowanie: Tak Aktualizowanie: Tak Czyszczenie: Tak

---

Zapytania

Kolumny liczb można odczytywać za pomocą pola column_values w zapytaniach items, używając wbudowanego fragmentu dla NumbersValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on NumbersValue {
        id
        number
        symbol
        direction
        text
        value
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on NumbersValue {
          id
          number
          symbol
          direction
          text
          value
        }
      }
    }
  }
`;

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

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

Pola

Możesz użyć następujących pól, aby określić, jakie informacje zwróci implementacja NumbersValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
direction NumberValueUnitDirection	Określa położenie symbolu jednostki względem liczby: left lub right.
id ID!	Unikalny identyfikator kolumny.
is_leaf Boolean!	Określa, czy ten element nie ma podelementów. Na tablicach wielopoziomowych z możliwością agregacji wartość false oznacza, że jest to obliczona wartość agregacji z elementów podrzędnych, a nie wartość statyczna.
number Float	Wartość liczbowa w kolumnie. Zwraca null, jeśli kolumna jest pusta.
symbol String	Symbol jednostki przypisany do kolumny (np. $, %). Zwraca null, jeśli nie skonfigurowano jednostki.
text String	Wartość kolumny w postaci tekstu. Zwraca "", jeśli kolumna nie ma wartości.
type ColumnType!	Typ kolumny.
value JSON	Surowa wartość kolumny w postaci ciągu JSON. Zwraca null, jeśli kolumna jest pusta.

NumberValueUnitDirection

Wyliczenie określające położenie symbolu jednostki wartości liczbowej.

Wartość wyliczenia	Opis
left	Symbol jest umieszczony po lewej stronie liczby.
right	Symbol jest umieszczony po prawej stronie liczby.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Project Alpha",
        "column_values": [
          {
            "id": "numbers",
            "number": 4.5,
            "symbol": "$",
            "direction": "left",
            "text": "4.50",
            "value": "\"4.50\""
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

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

Operator	Wartość porównania	Opis
any_of	Wartość liczbowa lub "$$$blank$$$"	Zwraca elementy, których wartość jest zgodna z dowolną z podanych liczb. Użyj "$$$blank$$$", aby uwzględnić puste wartości.
not_any_of	Wartość liczbowa lub "$$$blank$$$"	Pomija elementy, których wartość jest zgodna z dowolną z podanych liczb. Użyj "$$$blank$$$", aby pominąć puste wartości.
greater_than	Wartość liczbowa	Zwraca elementy, których wartość jest ściśle większa od podanej liczby.
greater_than_or_equals	Wartość liczbowa	Zwraca elementy, których wartość jest większa od podanej liczby lub jej równa.
lower_than	Wartość liczbowa	Zwraca elementy, których wartość jest ściśle mniejsza od podanej liczby.
lower_than_or_equals	Wartość liczbowa	Zwraca elementy, których wartość jest mniejsza od podanej liczby lub jej równa.
is_empty	[]	Zwraca elementy, których wartość liczbowa jest pusta (nie została ustawiona).
is_not_empty	[]	Zwraca elementy, dla których ustawiono wartość liczbową.

Przykłady

Filtrowanie według wartości większej niż

Ten przykład zwraca wszystkie elementy, których wartość w kolumnie liczb jest większa niż 5.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "numbers"
            compare_value: [5]
            operator: greater_than
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on NumbersValue {
            number
          }
        }
      }
    }
  }
}

Filtrowanie według dokładnej wartości

Ten przykład zwraca wszystkie elementy, których wartość w kolumnie liczb wynosi 100.

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

Filtrowanie według pustej wartości

Ten przykład zwraca wszystkie elementy, których kolumna liczb jest pusta.

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

---

Mutacje

Tworzenie

Wymagany zakres uprawnień: boards:write

Kolumnę liczb możesz utworzyć za pomocą ogólnej mutacji create_column. Nie ma osobnej mutacji create_numbers_column.

mutation {
  create_column(
    board_id: 1234567890
    column_type: numbers
    title: "Budget"
    description: "Project budget in USD"
    defaults: "{\"unit\":{\"symbol\":\"$\",\"direction\":\"left\",\"precision\":2}}"
  ) {
    id
    title
    description
  }
}

Na tablicach wielopoziomowych kolumny liczb są domyślnie tworzone z agregacją SUM. Możesz wskazać inną funkcję lub wyłączyć agregację:

mutation {
  create_column(
    board_id: 1234567890
    column_type: numbers
    title: "Budget"
    capabilities: { calculated: { function: SUM } }
  ) {
    id
    title
  }
}

Aby wyłączyć agregację, przekaż function: NONE:

mutation {
  create_column(
    board_id: 1234567890
    column_type: numbers
    title: "Reference Number"
    capabilities: { calculated: { function: NONE } }
  ) {
    id
    title
  }
}

Ustawienia kolumny

Możesz skonfigurować jednostkę i sposób wyświetlania kolumny za pomocą argumentu defaults. Przekaż ciąg JSON o następującej strukturze:

Właściwość	Typ	Opis
unit.symbol	String	Symbol jednostki do wyświetlenia (np. "$", "%", "custom"). Użyj "custom" razem z custom_unit.
unit.custom_unit	String	Własny ciąg jednostki, gdy symbol ma wartość "custom".
unit.direction	String	Położenie symbolu: "left" lub "right".
unit.precision	Integer	Liczba miejsc po przecinku. Możliwe wartości: -1 (automatycznie) oraz od 0 do 5.
hide_footer	Boolean	Określa, czy ukryć podsumowanie w stopce kolumny.

Aktualizowanie wartości

Możesz zaktualizować wartość w kolumnie liczb za pomocą mutacji change_simple_column_value lub change_multiple_column_values. W zależności od wybranej mutacji możesz przekazać wartości jako zwykłe ciągi znaków lub obiekty JSON.

change_simple_column_value

Przekaż ciąg znaków zawierający liczbę całkowitą lub zmiennoprzecinkową.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "numbers"
    value: "42.5"
  ) {
    id
  }
}

const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnId: String!, $value: String!) {
    change_simple_column_value(
      item_id: $itemId
      board_id: $boardId
      column_id: $columnId
      value: $value
    ) {
      id
    }
  }
`;

const variables = {
  boardId: "1234567890",
  itemId: "9876543210",
  columnId: "numbers",
  value: "42.5"
};

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

change_multiple_column_values

Przekaż wartość liczbową jako ciąg znaków w obiekcie JSON.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"numbers\": \"42.5\"}"
  ) {
    id
  }
}

Ustawianie wartości podczas tworzenia elementu

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

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"numbers\": \"100\"}"
  ) {
    id
    name
  }
}

Czyszczenie wartości

Możesz wyczyścić wartość w kolumnie liczb za pomocą mutacji change_simple_column_value lub change_multiple_column_values.

change_simple_column_value

Przekaż pusty ciąg znaków w polu value.

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

change_multiple_column_values

Przekaż null w polu column_values.

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

---

Odczytywanie konfiguracji kolumny

Aby sprawdzić ustawienia jednostki kolumny liczb, możesz odczytać jej konfigurację za pomocą pola settings.

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

Struktura odpowiedzi settings

Pole settings zwraca typowany obiekt JSON z następującymi kluczami:

Klucz	Typ	Opis
unit	Object	Obiekt konfiguracji jednostki. Pusty ({}), jeśli nie skonfigurowano jednostki.
unit.symbol	String	Symbol jednostki (np. "$", "%", "custom").
unit.custom_unit	String	Własny ciąg jednostki używany, gdy symbol ma wartość "custom".
unit.direction	String	Położenie symbolu względem wartości: "left" lub "right".
unit.precision	Integer	Liczba miejsc po przecinku: -1 (automatycznie) lub od 0 do 5.
hide_footer	Boolean	Określa, czy podsumowanie w stopce jest ukryte.

Przykładowa odpowiedź settings

Kolumna skonfigurowana z symbolem dolara:

{
  "unit": {
    "symbol": "$",
    "custom_unit": "",
    "direction": "left"
  }
}

Kolumna bez skonfigurowanej jednostki:

{}

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny liczb 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: numbers
  )
}

{
  "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": {
              "unit": {
                "type": "object",
                "properties": {
                  "symbol": {
                    "type": "string",
                    "description": "Unit symbol type (e.g., \"custom\", \"$\", etc.)"
                  },
                  "custom_unit": {
                    "type": "string",
                    "description": "Custom unit symbol when symbol is \"custom\""
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "left",
                      "right"
                    ],
                    "description": "Position of the unit symbol relative to the value"
                  },
                  "precision": {
                    "type": "integer",
                    "enum": [
                      -1,
                      0,
                      1,
                      2,
                      3,
                      4,
                      5
                    ],
                    "description": "Number of decimal places to display (-1 for automatic)"
                  }
                },
                "additionalProperties": false
              },
              "hide_footer": {
                "type": "boolean",
                "description": "Whether to hide the footer"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

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