Dokumentacja dla programistów

Data

Aktualizacja 2026-09-06

Kolumna daty reprezentuje konkretną datę i opcjonalnie godzinę. Służy do określania terminów, kamieni milowych, planowania i śledzenia informacji powiązanych z datami.

Za pomocą API kolumnę daty można odczytywać, filtrować, aktualizować i czyścić.

Typ kolumny Typ implementacji Obsługiwane operacje
date DateValue
  • Odczyt: tak
  • Filtrowanie: tak
  • Aktualizacja: tak
  • Czyszczenie: tak

Zapytania

Kolumny daty można odpytywać za pomocą pola column_values w zapytaniach items, używając wbudowanego fragmentu dla DateValue.

Na tablicach wielopoziomowych kolumny daty z funkcją agregacji wymagają ustawienia capabilities: [CALCULATED] w polu column_values, aby zwracać jakiekolwiek wartości. Bez tego API zwraca pustą tablicę - nawet dla elementów najniższego poziomu ze stałymi wartościami.

Kolumny daty z agregacją zachowują typ DateValue. Użyj pola is_leaf, aby odróżnić wartości statyczne (true) od obliczonych wartości agregacji (false).

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on DateValue {
        id
        date
        time
        text
        value
        updated_at
      }
    }
  }
}
const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on DateValue {
          id
          date
          time
          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 DateValue.

Pole Opis
column Column! Kolumna, do której należy wartość.
date String Wartość daty w formacie YYYY-MM-DD. Zwraca "", jeśli kolumna nie ma wartości.
icon String Wybrana ikona w postaci ciągu znaków.
id ID! Unikalny identyfikator kolumny.
is_leaf Boolean! Informuje, czy ten element nie ma podelementów. Na tablicach wielopoziomowych z funkcją agregacji wartość false oznacza obliczoną wartość agregacji z elementów podrzędnych, a nie wartość statyczną.
text String Sformatowana data i opcjonalna godzina w strefie czasowej użytkownika. Zwraca "", jeśli kolumna nie ma wartości.
time String Godzina przeliczona na strefę czasową użytkownika. Zwraca "", jeśli nie ustawiono godziny.
type ColumnType! Typ kolumny.
updated_at Date Data ostatniej aktualizacji kolumny.
value JSON Surowa wartość kolumny w formacie JSON. Zawiera date i time w UTC. Zwraca null, jeśli kolumna nie ma wartości.

Pole time i godzina w polu text są automatycznie przeliczane na strefę czasową użytkownika wykonującego wywołanie API. Pole value zawsze przechowuje godziny w UTC.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "date",
            "date": "2026-06-15",
            "time": "12:00",
            "text": "2026-06-15 12:00",
            "value": "{\"date\":\"2026-06-15\",\"time\":\"09:00:00\",\"changed_at\":\"2026-03-21T08:36:10.897Z\"}",
            "updated_at": "2026-03-21T08:36:10+00:00"
          }
        ]
      }
    ]
  }
}

Filtrowanie

Możesz filtrować elementy według wartości w kolumnie daty za pomocą obiektu items_page.

Niektóre wartości porównania są dynamiczne (np. "TODAY", "THIS_WEEK") i zależą od godziny, strefy czasowej, formatu daty oraz pierwszego dnia tygodnia ustawionych przez użytkownika wykonującego wywołanie API. Inne są statyczne (np. "EXACT" z konkretną datą).

Wyniki zależą od strefy czasowej, formatu daty i pierwszego dnia tygodnia skonfigurowanych w profilu monday.com użytkownika wykonującego wywołanie API.

Poniższa tabela przedstawia obsługiwane wartości porównania i zgodne z nimi operatory.

Wartość porównania Opis Operatory
"TODAY" Elementy z datą przypadającą na dziś.
  • any_of: elementy z datą przypadającą na dziś
  • not_any_of: elementy z datą inną niż dzisiejsza
  • greater_than: daty późniejsze niż dzisiejsza
  • greater_than_or_equals: daty przypadające dziś lub później
  • lower_than: daty wcześniejsze niż dzisiejsza
  • lower_than_or_equal: daty przypadające dziś lub wcześniej
"TOMORROW" Elementy z datą przypadającą na jutro.
  • any_of: elementy z datą przypadającą jutro
  • not_any_of: elementy z datą inną niż jutrzejsza
  • greater_than: daty późniejsze niż jutrzejsza
  • greater_than_or_equals: daty przypadające jutro lub później
  • lower_than: daty wcześniejsze niż jutrzejsza
  • lower_than_or_equal: daty przypadające jutro lub wcześniej
"YESTERDAY" Elementy z datą przypadającą na wczoraj.
  • any_of: elementy z datą przypadającą wczoraj
  • not_any_of: elementy z datą inną niż wczorajsza
  • greater_than: daty późniejsze niż wczorajsza
  • greater_than_or_equals: daty przypadające wczoraj lub później
  • lower_than: daty wcześniejsze niż wczorajsza
  • lower_than_or_equal: daty przypadające wczoraj lub wcześniej
"THIS_WEEK" Elementy z datą przypadającą w bieżącym tygodniu. Pierwszy dzień tygodnia jest określany na podstawie ustawień konta użytkownika wykonującego wywołanie API.
  • any_of: daty z bieżącego tygodnia
  • not_any_of: daty spoza bieżącego tygodnia
  • greater_than: daty późniejsze niż bieżący tydzień
  • greater_than_or_equals: daty przypadające w bieżącym tygodniu lub później
  • lower_than: daty wcześniejsze niż bieżący tydzień
  • lower_than_or_equal: daty przypadające w bieżącym tygodniu lub wcześniej
"ONE_WEEK_AGO" Elementy z datą przypadającą w poprzednim tygodniu. Pierwszy dzień tygodnia jest określany na podstawie ustawień konta użytkownika wykonującego wywołanie API.
  • any_of: daty z poprzedniego tygodnia
  • not_any_of: daty spoza poprzedniego tygodnia
  • greater_than: daty późniejsze niż poprzedni tydzień
  • greater_than_or_equals: daty przypadające w poprzednim tygodniu lub później
  • lower_than: daty wcześniejsze niż poprzedni tydzień
  • lower_than_or_equal: daty przypadające w poprzednim tygodniu lub wcześniej
"ONE_WEEK_FROM_NOW" Elementy z datą przypadającą w nadchodzącym tygodniu. Pierwszy dzień tygodnia jest określany na podstawie ustawień konta użytkownika wykonującego wywołanie API.
  • any_of: daty z nadchodzącego tygodnia
  • not_any_of: daty spoza nadchodzącego tygodnia
  • greater_than: daty późniejsze niż nadchodzący tydzień
  • greater_than_or_equals: daty przypadające w nadchodzącym tygodniu lub później
  • lower_than: daty wcześniejsze niż nadchodzący tydzień
  • lower_than_or_equal: daty przypadające w nadchodzącym tygodniu lub wcześniej
"THIS_MONTH" Elementy z datą przypadającą w bieżącym miesiącu.
  • any_of: daty z bieżącego miesiąca
  • not_any_of: daty spoza bieżącego miesiąca
  • greater_than: daty późniejsze niż bieżący miesiąc
  • greater_than_or_equals: daty przypadające w bieżącym miesiącu lub później
  • lower_than: daty wcześniejsze niż bieżący miesiąc
  • lower_than_or_equal: daty przypadające w bieżącym miesiącu lub wcześniej
"ONE_MONTH_AGO" Elementy z datą przypadającą w poprzednim miesiącu.
  • any_of: daty z poprzedniego miesiąca
  • not_any_of: daty spoza poprzedniego miesiąca
  • greater_than: daty późniejsze niż poprzedni miesiąc
  • greater_than_or_equals: daty przypadające w poprzednim miesiącu lub później
  • lower_than: daty wcześniejsze niż poprzedni miesiąc
  • lower_than_or_equal: daty przypadające w poprzednim miesiącu lub wcześniej
"ONE_MONTH_FROM_NOW" Elementy z datą przypadającą w nadchodzącym miesiącu.
  • any_of: daty z nadchodzącego miesiąca
  • not_any_of: daty spoza nadchodzącego miesiąca
  • greater_than: daty późniejsze niż nadchodzący miesiąc
  • greater_than_or_equals: daty przypadające w nadchodzącym miesiącu lub później
  • lower_than: daty wcześniejsze niż nadchodzący miesiąc
  • lower_than_or_equal: daty przypadające w nadchodzącym miesiącu lub wcześniej
"PAST_DATETIME" Elementy z datą i godziną przypadającymi w przeszłości.
  • any_of: data i godzina z przeszłości
  • not_any_of: data i godzina, które nie przypadają w przeszłości
"FUTURE_DATETIME" Elementy z datą i godziną przypadającymi w przyszłości.
  • any_of: data i godzina z przyszłości
  • not_any_of: data i godzina, które nie przypadają w przyszłości
"UPCOMING" Używane z kolumną statusu. Zwraca elementy, które nie są oznaczone jako „Done” i których data jeszcze nie minęła. Elementy z datą przypadającą na dziś nie są uznawane za nadchodzące.
  • any_of: elementy, które nie są oznaczone jako „Done” przed upływem daty
  • not_any_of: elementy oznaczone jako „Done” przed upływem daty
"OVERDUE" Używane z kolumną statusu. Zwraca elementy, które nie są oznaczone jako „Done” i których data minęła. Elementy z datą przypadającą na dziś są uznawane za zaległe od następnego dnia.
  • any_of: elementy, które nie są oznaczone jako „Done” po upływie daty
  • not_any_of: elementy oznaczone jako „Done” po upływie daty
"DONE_ON_TIME" Używane z kolumną statusu. Zwraca elementy oznaczone jako „Done” przed datą ustawioną w kolumnie daty.
  • any_of: ukończone przed datą
  • not_any_of: nieukończone przed datą
"DONE_OVERDUE" Używane z kolumną statusu. Zwraca elementy oznaczone jako „Done” po dacie ustawionej w kolumnie daty.
  • any_of: ukończone po dacie
  • not_any_of: nieukończone po dacie
Daty dokładne z "EXACT" (np. ["EXACT", "2026-07-01"]) Użyj dat statycznych w formacie YYYY-MM-DD w połączeniu ze słowem kluczowym "EXACT".
  • any_of: elementy z określoną datą
  • not_any_of: elementy bez określonej daty
  • greater_than: daty późniejsze niż określona data
  • greater_than_or_equals: daty przypadające w określonym dniu lub później
  • lower_than: daty wcześniejsze niż określona data
  • lower_than_or_equal: daty przypadające w określonym dniu lub wcześniej
  • between: elementy z datami z zakresu dwóch dat (zobacz przykład poniżej)
"$$$blank$$$" Elementy z pustą wartością daty.
  • any_of: elementy z pustą wartością
  • not_any_of: elementy z niepustą wartością

Możesz też użyć operatorów is_empty i is_not_empty z pustą wartością porównania ([]), aby filtrować elementy z ustawioną datą lub bez niej.

Przykłady

Filtrowanie według konkretnej daty

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["EXACT", "2026-07-01"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}
const query = `
  query ($boardId: [ID!], $columnId: ID!, $operator: ItemsQueryRuleOperator!, $compareValue: CompareValue!) {
    boards(ids: $boardId) {
      items_page(
        query_params: {
          rules: [
            { column_id: $columnId, compare_value: $compareValue, operator: $operator }
          ]
        }
      ) {
        items { id name }
      }
    }
  }
`;

const variables = {
  boardId: [1234567890],
  columnId: "date",
  compareValue: ["EXACT", "2026-07-01"],
  operator: "any_of",
};

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

Filtrowanie według wielu wartości porównania

W jednej regule możesz połączyć wiele dynamicznych i statycznych wartości porównania. Każde słowo kluczowe "EXACT" dotyczy daty, która występuje bezpośrednio po nim.

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: [
              "EXACT"
              "2026-09-10"
              "TODAY"
              "EXACT"
              "2026-09-11"
              "TOMORROW"
            ]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}
const query = `
  query ($boardId: [ID!], $columnId: ID!, $operator: ItemsQueryRuleOperator!, $compareValue: CompareValue!) {
    boards(ids: $boardId) {
      items_page(
        query_params: {
          rules: [
            { column_id: $columnId, compare_value: $compareValue, operator: $operator }
          ]
        }
      ) {
        items { id name }
      }
    }
  }
`;

const variables = {
  boardId: [1234567890],
  columnId: "date",
  compareValue: ["EXACT", "2026-09-10", "TODAY", "EXACT", "2026-09-11", "TOMORROW"],
  operator: "any_of",
};

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

Filtrowanie dat przypadających w bieżącym tygodniu lub później

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

Filtrowanie według zakresu dwóch dat

Operator between przyjmuje dwie daty w formacie YYYY-MM-DD i zwraca elementy z datami należącymi do tego zakresu, włącznie z jego granicami.

query {
  boards(ids: [1234567890]) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["2026-06-01", "2026-12-31"]
            operator: between
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Filtrowanie według "UPCOMING"

Zwraca elementy, które nie są oznaczone jako „Done” i których data jeszcze nie minęła. Wymaga, aby na tablicy znajdowała się kolumna statusu.

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

Filtrowanie pustych wartości daty

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

Mutacje

Tworzenie

Wymagany zakres uprawnień: boards:write

Kolumnę daty możesz utworzyć za pomocą ogólnej mutacji create_column, ustawiając column_type: date.

mutation {
  create_column(
    board_id: 1234567890
    column_type: date
    title: "Deadline"
  ) {
    id
    title
  }
}

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

mutation {
  create_column(
    board_id: 1234567890
    column_type: date
    title: "Deadline"
    capabilities: { calculated: { function: MIN } }
  ) {
    id
    title
  }
}

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

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

Aktualizowanie wartości

Kolumnę daty możesz zaktualizować 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.

Na tablicach wielopoziomowych mutacje dotyczące elementów nadrzędnych z obliczonymi wartościami agregacji nie zwracają błędu - API zwraca odpowiedź informującą o powodzeniu, ale wartość się nie zmienia. Zaktualizuj zamiast tego elementy podrzędne.

change_simple_column_value

Przekaż datę jako ciąg znaków w formacie YYYY-MM-DD. Opcjonalnie dodaj godzinę w formacie HH:MM:SS, oddzielając ją spacją. Wartości powinny być podane w UTC, ponieważ w interfejsie są automatycznie przeliczane na strefę czasową użytkownika.

Sama data

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "date"
    value: "2026-06-15"
  ) {
    id
  }
}

Data z godziną

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "date"
    value: "2026-06-15 09:00:00"
  ) {
    id
  }
}
const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValue: String!, $columnId: String!) {
    change_simple_column_value(
      item_id: $itemId
      board_id: $boardId
      column_id: $columnId
      value: $columnValue
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnId: "date",
  columnValue: "2026-06-15 09:00:00",
};

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

change_multiple_column_values

Przekaż klucze date i opcjonalnie time jako obiekt JSON w column_values. Klucz date używa formatu YYYY-MM-DD, a klucz time - formatu HH:MM:SS (UTC).

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"date\": {\"date\": \"2026-06-15\", \"time\": \"09:00:00\"}}"
  ) {
    id
  }
}
const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    date: {
      date: "2026-06-15",
      time: "09:00:00"
    }
  }),
};

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

Pomiń klucz time, jeśli chcesz ustawić samą datę. Gdy godzina nie jest ustawiona, pole time zwraca "", a surowa wartość value zawiera "time": null.

Ustawianie daty podczas tworzenia elementu

Datę możesz ustawić podczas tworzenia elementu, przekazując wartość kolumny daty w argumencie column_values.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"date\": {\"date\": \"2026-06-15\", \"time\": \"09:00:00\"}}"
  ) {
    id
    name
  }
}

Czyszczenie

Kolumnę daty możesz wyczyścić za pomocą 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: "date"
    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: "{\"date\": null}"
  ) {
    id
  }
}
const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

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

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

Odczytywanie konfiguracji kolumny

Aby sprawdzić ustawienia wyświetlania kolumny daty, możesz pobrać jej konfigurację za pomocą pola settings.

Pole settings_str jest przestarzałe od wersji API 2025-10. Zamiast niego użyj typowanego obiektu settings, który zwraca uporządkowany JSON, a nie ciąg znaków zakodowany jako JSON.

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

Struktura odpowiedzi settings

Pole settings zwraca typowany obiekt JSON zawierający następujące klucze:

Klucz Typ Opis
show_current_year boolean Określa, czy w widoku daty wyświetlać bieżący rok.
show_week_day boolean Określa, czy wyświetlać dzień tygodnia.
show_week_number boolean Określa, czy wyświetlać numer tygodnia.
show_time_by_default boolean Określa, czy domyślnie wyświetlać godzinę w kolumnie.
hide_footer boolean Określa, czy ukrywać stopkę w selektorze daty.
use_numeric_only_format boolean Określa, czy używać wyłącznie liczbowego formatu daty (np. 03/21/2026 zamiast Mar 21, 2026).
show_add_icon boolean Określa, czy wyświetlać ikonę dodawania.
show_weekends boolean Określa, czy wyświetlać weekendy w selektorze daty.
calcType string Typ obliczeń przy agregowaniu dat. Jedna z wartości: earliestToLatest, earliest lub latest.
date_format string Konfiguracja formatu daty.
time_format string Konfiguracja formatu godziny.

Kolumna daty z domyślnymi ustawieniami zwraca pusty obiekt settings ({}). W odpowiedzi pojawiają się tylko ustawienia niestandardowe.


Pobieranie schematu typu kolumny

Schemat JSON ustawień kolumny daty możesz pobrać programowo 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: date
  )
}
{
  "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": {
              "show_current_year": {
                "type": "boolean",
                "description": "Whether to show the current year"
              },
              "show_week_day": {
                "type": "boolean",
                "description": "Whether to show the day of the week"
              },
              "show_week_number": {
                "type": "boolean",
                "description": "Whether to show the week number"
              },
              "show_time_by_default": {
                "type": "boolean",
                "description": "Whether to show time by default"
              },
              "hide_footer": {
                "type": "boolean",
                "description": "Whether to hide the footer"
              },
              "use_numeric_only_format": {
                "type": "boolean",
                "description": "Whether to use numeric only format"
              },
              "show_add_icon": {
                "type": "boolean",
                "description": "Whether to show the add icon"
              },
              "show_weekends": {
                "type": "boolean",
                "description": "Whether to show weekends"
              },
              "calcType": {
                "type": "string",
                "description": "Calculation type for date column",
                "enum": ["earliestToLatest", "earliest", "latest"]
              },
              "state": {
                "type": "integer",
                "description": "Column state",
                "enum": [0, 1]
              },
              "date_format": {
                "type": "string",
                "description": "Date format configuration"
              },
              "time_format": {
                "type": "string",
                "description": "Time format configuration"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

Odpowiedź zawiera nazwy właściwości, typy, ograniczenia (np. dozwolone wartości) i opisy każdego ustawienia. 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.