Kolumna łączenia tablic łączy element na jednej tablicy z jednym lub większą liczbą elementów na innej tablicy albo na tej samej tablicy. Umożliwia tworzenie relacji między tablicami. Jest często używana do określania zależności między projektami, łączenia powiązanych zadań i tworzenia powiązań w CRM.

Za pomocą API kolumna łączenia tablic obsługuje odczyt, filtrowanie, tworzenie, aktualizowanie i czyszczenie wartości.

Typ kolumny	Typ implementacji	Obsługiwane operacje
board_relation	BoardRelationValue	Odczyt: tak Filtrowanie: tak Tworzenie: tak Aktualizowanie: tak Czyszczenie: tak

---

Zapytania

Kolumny łączenia tablic można odpytywać za pomocą pola column_values w zapytaniach items, używając wbudowanego fragmentu dla BoardRelationValue.

Pobieranie identyfikatorów połączonych tablic

Główne zapytanie connection_board_ids zwraca identyfikatory wszystkich tablic połączonych z określoną kolumną łączenia tablic.

• Wymagany zakres: boards:read
• Zwraca [ID!]! - tablicę identyfikatorów tablic
• Można go odpytywać tylko bezpośrednio na głównym poziomie

query {
  connection_board_ids(connection_id: "1234567890")
}

Argumenty

Argument	Typ	Opis
connection_id	ID!	Unikalny identyfikator kolumny łączenia tablic, której dotyczy zapytanie.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on BoardRelationValue {
        id
        display_value
        linked_item_ids
        linked_items {
          id
          name
        }
        updated_at
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on BoardRelationValue {
          id
          display_value
          linked_item_ids
          linked_items {
            id
            name
          }
          updated_at
        }
      }
    }
  }
`;

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

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

Pola

Możesz użyć poniższych pól, aby określić, jakie informacje zwróci implementacja BoardRelationValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
display_value String!	Nazwy połączonych elementów oddzielone przecinkami.
id ID!	Unikalny identyfikator kolumny.
linked_item_ids [ID!]!	Unikalne identyfikatory połączonych elementów.
linked_items [Item!]!	Połączone elementy. Możesz odpytywać dowolne pole Item połączonych elementów.
text String	Dla tej kolumny zawsze zwraca null. Zamiast tego użyj display_value.
type ColumnType!	Typ kolumny (board_relation).
updated_at Date	Data ostatniej aktualizacji kolumny.
value JSON	Dla tej kolumny zawsze zwraca null. Zamiast tego użyj linked_items i linked_item_ids.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Project Alpha",
        "column_values": [
          {
            "id": "connect_boards",
            "display_value": "Task A, Task B",
            "linked_item_ids": ["1122334455", "5544332211"],
            "linked_items": [
              { "id": "1122334455", "name": "Task A" },
              { "id": "5544332211", "name": "Task B" }
            ],
            "updated_at": "2026-03-21T12:00:00+00:00"
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

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

Operator	Wartość porównawcza	Opis
any_of	Tablica identyfikatorów połączonych elementów jako liczb (np. [1234567890])	Zwraca elementy połączone z dowolnym ze wskazanych elementów.
not_any_of	Tablica identyfikatorów połączonych elementów jako liczb (np. [1234567890])	Wyklucza elementy połączone z dowolnym ze wskazanych elementów.
contains_text	Fragment lub cała nazwa elementu jako ciąg znaków (np. ["Task"])	Zwraca elementy, których nazwa połączonego elementu zawiera wskazany tekst.
not_contains_text	Fragment lub cała nazwa elementu jako ciąg znaków (np. ["Task"])	Zwraca elementy, których nazwa żadnego z połączonych elementów nie zawiera wskazanego tekstu.
is_empty	[]	Zwraca elementy, które nie są połączone z innymi elementami.
is_not_empty	[]	Zwraca elementy połączone z co najmniej jednym innym elementem.

Przykłady

Filtrowanie według identyfikatora połączonego elementu

Ten przykład zwraca wszystkie elementy połączone z określonym elementem.

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

Filtrowanie według nazwy połączonego elementu

Ten przykład zwraca wszystkie elementy połączone z elementem, którego nazwa zawiera tekst „Task”.

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

Filtrowanie według pustego połączenia

Ten przykład zwraca wszystkie elementy, które nie są połączone z innymi elementami.

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

---

Mutacje

Tworzenie

Wymagany zakres: boards:write

Możesz utworzyć kolumnę łączenia tablic za pomocą mutacji create_column. Użyj argumentu defaults, aby określić docelową tablicę i ustawienia połączenia.

mutation {
  create_column(
    board_id: 1234567890
    title: "Related Items"
    column_type: board_relation
    defaults: {
      boardIds: [9876543210]
      allowMultipleItems: true
      allowCreateReflectionColumn: true
    }
  ) {
    id
    title
    type
  }
}

Argumenty defaults

Argument	Typ	Opis
boardIds	[Int]	Tablica identyfikatorów tablic, z którymi ma zostać utworzone połączenie. Wymagany jest co najmniej jeden identyfikator tablicy.
allowMultipleItems	Boolean	Określa, czy można łączyć wiele elementów. Domyślnie true.
allowCreateReflectionColumn	Boolean	Określa, czy na połączonej tablicy ma zostać utworzona kolumna mirror (dwukierunkowa). Domyślnie false.

Aktualizowanie

Możesz zaktualizować kolumnę łączenia tablic za pomocą mutacji change_multiple_column_values, przekazując identyfikatory połączonych elementów w tablicy item_ids.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"connect_boards\": {\"item_ids\": [1122334455, 5544332211]}}"
  ) {
    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({
    connect_boards: { item_ids: [1122334455, 5544332211] }
  }),
};

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

Ustawianie podczas tworzenia elementu

Możesz ustawić połączone elementy podczas tworzenia elementu, przekazując wartość kolumny w argumencie column_values mutacji create_item.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"connect_boards\": {\"item_ids\": [1122334455]}}"
  ) {
    id
    name
  }
}

Czyszczenie

Możesz wyczyścić kolumnę łączenia tablic za pomocą mutacji change_multiple_column_values, przekazując null jako wartość kolumny.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"connect_boards\": 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({
    connect_boards: null
  }),
};

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

---

Odczytywanie konfiguracji kolumny

Aby poznać ustawienia kolumny łączenia tablic, możesz odpytać jej konfigurację za pomocą pola settings kolumny.

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

Struktura odpowiedzi settings

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

Klucz	Typ	Opis
boardIds	number[]	Tablica identyfikatorów tablic, z którymi ta kolumna może się łączyć.
allowMultipleItems	boolean	Określa, czy w jednej komórce można połączyć wiele elementów.
allowCreateReflectionColumn	boolean	Określa, czy na połączonej tablicy utworzono kolumnę dwukierunkową (mirror). Występuje tylko wtedy, gdy ustawiono tę opcję.

Przykładowa odpowiedź settings

{
  "boardIds": [9876543210],
  "allowMultipleItems": true,
  "allowCreateReflectionColumn": true
}

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny łączenia tablic 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: board_relation
  )
}

{
  "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": {
              "allowCreateReflectionColumn": {
                "type": "boolean",
                "description": "Whether to allow creation of reflection columns"
              },
              "allowMultipleItems": {
                "type": "boolean",
                "description": "Whether to allow selection of multiple items"
              },
              "boardIds": {
                "type": "array",
                "description": "Array of related board IDs",
                "items": {
                  "type": "integer"
                }
              },
              "boardId": {
                "type": "integer",
                "description": "Default board ID for the relation"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

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