Zapytanie search pozwala znaleźć elementy, tablice, dokumenty i obszary robocze w całym koncie za pomocą jednego wywołania API. W tym przewodniku poznasz popularne sposoby wyszukiwania oraz dowiesz się, jak używać filtrów i opcji strategii, aby uzyskać precyzyjne wyniki w krótkim czasie.

Wymagania wstępne

• Token uwierzytelniający API
• Wymagane zakresy: boards:read dla wyników dotyczących elementów i tablic, docs:read dla wyników dotyczących dokumentów

Jak działa API wyszukiwania

Zapytanie search zwraca obiekt SearchNamespace. Aby uzyskać wyniki, wywołaj pola tego obiektu - po jednym dla każdego typu encji:

search {
  items(query: "...", ...)  → SearchItemResults
  boards(query: "...", ...) → SearchBoardResults
  docs(query: "...", ...)   → SearchDocResults
}

Każde pole encji przyjmuje własne argumenty query, limit, date_range, strategy oraz filtry specyficzne dla danej encji. Uwzględnij tylko potrzebne pola encji - nieużywane pola nie zostaną wykonane.

Podstawowe wyszukiwanie

Najprostsze zapytanie wyszukuje jeden typ encji. Użyj indexed_data, aby pobrać szybko dostępne, zindeksowane wcześniej pola:

query {
  search {
    items(query: "quarterly report", limit: 10) {
      results {
        id
        indexed_data {
          name
          board_id
          url
        }
      }
    }
  }
}

Wyszukiwanie wielu typów encji

Uwzględnij w jednym żądaniu wiele pól encji, aby jednocześnie wyszukiwać różne typy encji. Każde pole działa niezależnie i ma własne argumenty:

query {
  search {
    items(query: "quarterly report", limit: 10) {
      results {
        id
        indexed_data {
          name
          board_id
          url
        }
      }
    }
    boards(query: "quarterly report", limit: 10) {
      results {
        id
        indexed_data {
          name
          url
        }
      }
    }
    docs(query: "quarterly report", limit: 5) {
      results {
        id
        indexed_data {
          name
        }
      }
    }
  }
}

Filtrowanie według tablicy lub obszaru roboczego

Przekaż board_ids lub workspace_ids bezpośrednio jako argumenty pola encji.

Elementy na konkretnych tablicach

query {
  search {
    items(
      query: "design review"
      limit: 20
      board_ids: ["1234567890", "9876543210"]
    ) {
      results {
        id
        indexed_data {
          name
          board_id
          url
        }
      }
    }
  }
}

Wszystkie wyniki w obszarze roboczym

query {
  search {
    items(query: "roadmap", limit: 10, workspace_ids: ["12345"]) {
      results {
        id
        indexed_data { name board_id url }
      }
    }
    boards(query: "roadmap", limit: 10, workspace_ids: ["12345"]) {
      results {
        id
        indexed_data { name url }
      }
    }
    docs(query: "roadmap", limit: 10, workspace_ids: ["12345"]) {
      results {
        id
        indexed_data { name }
      }
    }
  }
}

Wyszukiwanie obszarów roboczych

query {
  search {
    workspaces(query: "engineering", limit: 10) {
      results {
        id
        indexed_data { name }
        live_data {
          id
          name
          created_at
        }
      }
    }
  }
}

Filtrowanie według zakresu dat

Użyj argumentu date_range, aby zawęzić wyniki na podstawie daty utworzenia lub aktualizacji. Możesz przekazać go niezależnie do dowolnego pola encji.

query {
  search {
    items(
      query: "sprint planning"
      limit: 10
      date_range: {
        created_after: "2026-01-01T00:00:00Z"
        updated_after: "2026-03-01T00:00:00Z"
      }
    ) {
      results {
        id
        indexed_data { name url }
      }
    }
    boards(
      query: "sprint planning"
      limit: 10
      date_range: {
        created_after: "2026-01-01T00:00:00Z"
      }
    ) {
      results {
        id
        indexed_data { name url }
      }
    }
  }
}

Wszystkie cztery pola daty są opcjonalne i można ich używać łącznie:

Pole	Opis
created_after	Zwraca tylko wyniki utworzone po tej dacie i godzinie
created_before	Zwraca tylko wyniki utworzone przed tą datą i godziną
updated_after	Zwraca tylko wyniki zaktualizowane po tej dacie i godzinie
updated_before	Zwraca tylko wyniki zaktualizowane przed tą datą i godziną

Wybór między jakością a szybkością

Użyj argumentu strategy, aby dostosować kompromis między jakością wyników wyszukiwania a czasem odpowiedzi:

Wartość	Działanie
SPEED	Szybsze wyniki o niższej jakości wyszukiwania
BALANCED	Dobra jakość i rozsądny czas odpowiedzi. Wartość domyślna.
QUALITY	Najlepsza jakość i dłuższy czas odpowiedzi

query {
  search {
    items(query: "critical bug", limit: 10, strategy: QUALITY) {
      results {
        id
        indexed_data { name url }
      }
    }
  }
}

Użyj SPEED w przypadku podpowiedzi podczas wpisywania lub autouzupełniania. Wybierz QUALITY, gdy precyzja jest ważniejsza niż opóźnienie.

Używanie live_data do pobierania aktualnych pól

Każdy wynik zawiera pole live_data, które zwraca pełną encję z podstawowego API. Użyj go, gdy potrzebujesz pól niedostępnych w indexed_data, takich jak stan elementu lub zagnieżdżone relacje.

live_data jest pobierane przez federację GraphQL z podstawowego API, co wydłuża czas odpowiedzi w porównaniu z samym żądaniem wyszukiwania. Jeśli zależy Ci na krótkim czasie odpowiedzi lub często odczytujesz dane, używaj indexed_data i proś o live_data tylko dla konkretnych pól, które muszą być aktualne.

query {
  search {
    items(query: "onboarding", limit: 5) {
      results {
        id
        indexed_data {
          name
          url
        }
        live_data {
          id
          name
          state
          column_values {
            id
            text
          }
        }
      }
    }
  }
}

📘 UWAGA

live_data może mieć wartość null, jeśli encja została usunięta po zindeksowaniu, jest niedostępna dla użytkownika wysyłającego żądanie albo wystąpiło opóźnienie indeksowania. W takich przypadkach odpowiedź GraphQL zawiera również odpowiadający wpis w polu errors na najwyższym poziomie, informujący o nieudanym pobraniu live_data. Samo zapytanie wyszukiwania zakończyło się powodzeniem - nie udało się jedynie pobrać live_data dla tego wyniku. Obsłuż wartość null w kodzie klienta i przetwarzaj pozostałe wyniki.

Przykład użycia JavaScript SDK

import { ApiClient } from "@mondaydotcomorg/api";

const client = new ApiClient({ token: "YOUR_API_TOKEN" });

const query = `query {
  search {
    items(query: "Q1 planning", limit: 10, workspace_ids: ["12345"]) {
      results {
        id
        indexed_data { name board_id url }
      }
    }
    boards(query: "Q1 planning", limit: 10) {
      results {
        id
        indexed_data { name url }
      }
    }
  }
}`;

const response = await client.request(query);
console.log(response);

Limity i dobre praktyki

Ograniczenie	Wartość
Maksymalna wartość limit	20 dla każdego pola encji
Domyślna wartość limit	10 dla każdego pola encji
Stronicowanie	Nieobsługiwane - zwracane są wszystkie wyniki, maksymalnie do wartości limit

Dobre praktyki:

• Wysyłaj żądania tylko dla potrzebnych typów encji. Pominięcie pól encji pozwala uniknąć zbędnego przetwarzania.
• Używaj board_ids lub workspace_ids, aby zawęzić zestaw wyników i zwiększyć ich trafność.
• Przy częstym odczytywaniu danych wybieraj indexed_data zamiast live_data. Indeksowanie jest asynchroniczne, więc indexed_data może być opóźnione o kilka sekund (lub dłużej przy dużym obciążeniu) w stosunku do podstawowego API. Korzystaj z live_data tylko w przypadku pól, dla których takie opóźnienie jest nieakceptowalne.
• Używaj filtrów date_range, aby ograniczyć wyniki do odpowiedniego przedziału czasu, zwłaszcza na kontach z dużą ilością danych.
• Dobierz strategy do potrzeb - użyj SPEED, gdy liczy się krótki czas odpowiedzi, a QUALITY, gdy najważniejsza jest precyzja.
• Używaj konkretnych haseł wyszukiwania. Bardziej precyzyjne zapytania zwracają trafniejsze wyniki.
• Obsługuj null w live_data. Encje mogły zostać usunięte po zindeksowaniu.