Kolumna formuły oblicza wartości na podstawie wyrażeń matematycznych, funkcji tekstowych i odwołań do innych kolumn. Formuły są obliczane po stronie serwera i nie można ich zapisywać przez API.

Za pomocą API można odczytywać kolumnę formuły i ją tworzyć.

Typ kolumny	Typ implementacji	Obsługiwane operacje
formula	FormulaValue	Odczyt: Tak Filtrowanie: Nie Tworzenie: Tak (ogólne) Aktualizacja: Nie Czyszczenie: Nie

---

Zapytania

Możesz pobierać dane z kolumn formuł za pomocą pola column_values w items, używając wbudowanego fragmentu dla FormulaValue.

Obliczony wynik jest zwracany w polu display_value. Pola text i value nie są wypełniane dla kolumn formuł.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on FormulaValue {
        id
        display_value
        type
        column {
          title
        }
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!], $columnType: [ColumnType!]) {
    items(ids: $itemIds) {
      id
      name
      column_values(types: $columnType) {
        column { title id }
        ... on FormulaValue {
          display_value
        }
      }
    }
  }
`;

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

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 FormulaValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
display_value String!	Obliczony wynik kolumny formuły. To podstawowe pole służące do odczytywania wartości formuł. Podlega limitom.
id ID!	Unikalny identyfikator kolumny.
text String	Zwraca pusty ciąg znaków dla kolumn formuł. Zamiast tego użyj display_value.
type ColumnType!	Typ kolumny (formula).
value JSON	Zwraca null dla kolumn formuł. Zamiast tego użyj display_value.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "formula_mkl3sp",
            "display_value": "10",
            "type": "formula",
            "column": {
              "title": "Numbers + 5"
            }
          }
        ]
      }
    ]
  }
}

Limity

Pole display_value dla kolumn formuł podlega następującym limitom:

• Maksymalnie 10 000 wartości formuł na minutę
• Maksymalnie 5 kolumn formuł w jednym zapytaniu
• Nie obsługuje formuł odwołujących się do kolumn mirror ani connect boards

---

Filtrowanie

Kolumny formuł nie obsługują filtrowania za pomocą items_page. Próba filtrowania według kolumny formuły zwraca błąd nieprawidłowej reguły.

Aby filtrować według wyników formuły, pobierz display_value dla wszystkich elementów i filtruj je po stronie klienta albo użyj innej kolumny, w której przechowywana jest potrzebna wartość.

---

Mutacje

Tworzenie

Wymagany zakres uprawnień: boards:write

Nie ma mutacji typowanej create_formula_column. Użyj ogólnej mutacji create_column z column_type: formula i przekaż wyrażenie formuły w argumencie defaults.

mutation {
  create_column(
    board_id: 1234567890
    title: "Total Cost"
    column_type: formula
    defaults: "{\"settings\":{\"formula\":\"{numbers_col} * {rate_col}\"}}"
  ) {
    id
    title
    type
    settings
  }
}

Argumenty

Argument	Typ	Opis
board_id	ID!	Unikalny identyfikator tablicy.
title	String!	Tytuł kolumny.
column_type	ColumnType!	Musi mieć wartość formula.
defaults	JSON	Ciąg JSON zawierający ustawienia formuły. Zobacz format defaults.
description	String	Opis kolumny.
after_column_id	ID	Identyfikator kolumny, za którą ma zostać wstawiona nowa kolumna.
id	String	Niestandardowy identyfikator kolumny. Jeśli go nie podasz, zostanie wygenerowany automatycznie.

Format defaults

Argument defaults przyjmuje ciąg JSON o następującej strukturze:

{
  "settings": {
    "formula": "{column_id_1} + {column_id_2}"
  }
}

Pole formula zawiera wyrażenie formuły. Odwołuj się do innych kolumn, używając ich identyfikatorów ujętych w nawiasy klamrowe, np. {numeric_col}. Możesz używać standardowych funkcji formuł, takich jak IF, CONCATENATE i SUM.

Przykładowa odpowiedź

{
  "data": {
    "create_column": {
      "id": "formula_mkl3sp",
      "title": "Total Cost",
      "type": "formula",
      "settings": {"formula": "{numbers_col} * {rate_col}"}
    }
  }
}

Aktualizacja wartości

Nie można aktualizować kolumn formuł za pomocą API. Wynik formuły jest obliczany automatycznie na podstawie wartości w kolumnach, do których formuła się odwołuje.

Próba aktualizacji kolumny formuły zwraca błąd:

• change_simple_column_value: "column type FormulaColumn is not supporting changing the column value with simple column value"
• change_multiple_column_values: "This column type can not be updated or created (client side auto calculated column)"

Aby zmienić wynik formuły, zaktualizuj kolumny źródłowe, do których się ona odwołuje.

Czyszczenie

Nie można czyścić kolumn formuł za pomocą API. Aby zresetować obliczoną wartość formuły, wyczyść kolumny źródłowe, do których się ona odwołuje.

---

Odczytywanie konfiguracji kolumny

Możesz pobrać konfigurację kolumny formuły z pola settings kolumny, aby sprawdzić wyrażenie formuły.

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

Struktura odpowiedzi settings

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

Klucz	Typ	Opis
formula	string	Wyrażenie formuły. Odwołuje się do innych kolumn za pomocą ich identyfikatorów ujętych w nawiasy klamrowe, np. {numeric_col} + 5.
hide_footer	boolean	Określa, czy podsumowanie w stopce jest ukryte. Pojawia się tylko wtedy, gdy zostało jawnie ustawione.

Przykładowa odpowiedź settings

{
  "formula": "{numeric_mkl3sp} + 5"
}

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny formuły 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: formula
  )
}

{
  "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": {
              "formula": {
                "type": "string",
                "description": "Formula expression"
              },
              "hide_footer": {
                "type": "boolean",
                "description": "Whether to hide the footer"
              }
            },
            "additionalProperties": false,
            "required": [
              "formula"
            ]
          }
        }
      }
    }
  }
}

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ć tych danych do walidowania ustawień kolumn, dynamicznego generowania interfejsów lub przekazywania kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.