# Context pack: Poradniki Source: https://nordvec.com/pl/docs/guides/how-to Pack: https://nordvec.com/pl/docs/packs/how-to This pack bundles one Nordvec guide with the guides it builds on and the guides it links to, in reading order, so an assistant reading it meets no reference it cannot follow. ## Contents 1. [Poradniki](https://nordvec.com/pl/docs/guides/how-to) (this guide) 2. [Prześlij dokumenty ze swoich systemów](https://nordvec.com/pl/docs/guides/how-to/push-documents) (linked from this guide) 3. [Filtrowanie i precyzowanie wyszukiwania](https://nordvec.com/pl/docs/guides/how-to/filter-search) (linked from this guide) 4. [Przeglądaj i pobieraj dokumenty](https://nordvec.com/pl/docs/guides/how-to/list-documents) (linked from this guide) --- # Poradniki Source: https://nordvec.com/pl/docs/guides/how-to Krok po kroku instrukcje do typowych zadań API, od wyszukiwania i wyświetlania dokumentów po dodawanie własnych. Każdy przewodnik przeprowadza cię przez jedno zadanie, od pierwszego żądania do działającego wyniku, wraz z polami żądania, których używa, oraz odpowiedzią, którą otrzymasz. Aby poznać szczegóły każdego pola w każdej operacji, zajrzyj do [dokumentacji API](/docs/api). - [Prześlij dokumenty ze swoich systemów](https://nordvec.com/pl/docs/guides/how-to/push-documents): Utwórz źródło danych, prześlij do niego dokumenty za pomocą klucza API do indeksowania, wybierz, kto może je czytać, i wstrzymaj je lub usuń, gdy źródło się zmieni. - [Filtrowanie i precyzowanie wyszukiwania](https://nordvec.com/pl/docs/guides/how-to/filter-search): Ogranicz wyszukiwanie dokumentów za pomocą filtrów źródła danych, dostawcy, typu i daty, a następnie odczytaj wyniki uszeregowane według trafności. - [Przeglądaj i pobieraj dokumenty](https://nordvec.com/pl/docs/guides/how-to/list-documents): Przeglądaj swoje dokumenty za pomocą paginacji kursorowej, filtruj i sortuj je, a także pobierz jeden lub wiele po identyfikatorze. --- # Prześlij dokumenty ze swoich systemów Source: https://nordvec.com/pl/docs/guides/how-to/push-documents Utwórz źródło danych, prześlij do niego dokumenty za pomocą klucza API do indeksowania, wybierz, kto może je czytać, i wstrzymaj je lub usuń, gdy źródło się zmieni. Interfejs push API indeksuje dokumenty z systemów, dla których Nordvec nie ma łącznika: eksport wewnętrznej wiki, archiwum zgłoszeń, baza notatek. Przesyłasz tekst i informację, kto może go przeczytać; Nordvec przechowuje go w UE, indeksuje i sprawia, że jest przeszukiwalny i cytowalny jak każdy inny dokument. Każdy przesłany dokument trafia do **źródła danych**, nazwanej przestrzeni w Twojej przestrzeni roboczej, którą najpierw tworzy administrator przestrzeni roboczej. Przesłanie, które wskazuje źródło danych nieistniejące lub wstrzymane, jest odrzucane. ## Utwórz źródło danych [#utwórz-źródło-danych] Otwórz **Ustawienia przestrzeni roboczej > Źródła danych** i wybierz **Utwórz źródło danych**. Mogą to zrobić administratorzy i właściciele przestrzeni roboczej; w osobistej przestrzeni roboczej to ty. | Pole | Uwagi | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Nazwa | To, co widzą użytkownicy na liście ustawień. Do 200 znaków. | | Slug | To, co każde przesłanie wskazuje. Małe litery, cyfry, `-` i `_`, zaczynające się od litery lub cyfry, do 200 znaków. Nie można go później zmienić. | Slug `confluence-export` jest używany w przykładach poniżej. ## Utwórz klucz API do indeksowania [#utwórz-klucz-api-do-indeksowania] Uwierzytelnianie żądań push odbywa się za pomocą klucza API klasy **Indexing**, który zawiera zakres `index:write`. Dodaj `index:status`, aby śledzić proces indeksowania, oraz `index:delete`, aby usuwać dokumenty lub zastępować cały źródło danych. Utwórz go w **Ustawieniach przestrzeni > Klucze API**. Surowy klucz zaczyna się od `nv_eu_idx_` i jest wyświetlany tylko raz. Więcej informacji znajdziesz w [Uwierzytelnianiu](/docs/guides/authentication). Każde żądanie musi również zawierać identyfikator twojej przestrzeni roboczej jako `tenantId`, czyli identyfikator z adresu przestrzeni w aplikacji (`/w//...`), i musi to być przestrzeń, do której należy klucz. ## Prześlij jeden dokument [#prześlij-jeden-dokument] `/documents/push` tworzy dokument lub aktualizuje go, gdy dokument o tym samym `id` już istnieje w źródle danych. ```bash curl https://nordvec.com/api/v1/documents/push \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: page-4711-2026-09-28" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "document": { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/markdown", "content": "# Travel expenses\n..." }, "permissions": {}, "sourceUrl": "https://wiki.example.com/pages/4711", "type": "policy" } }' ``` ```json { "documentId": "page-4711", "status": "queued", "updated": false } ``` * `id` to Twój stabilny identyfikator dokumentu w źródle danych. Ponowne przesłanie tego samego `id` aktualizuje go; niezmieniona treść jest rozpoznawana po jej skrócie i nie jest indeksowana dwukrotnie. * `body.mimeType` to jeden z `text/plain`, `text/markdown`, `text/html`, `application/pdf` lub typy Word, Excel i PowerPoint (`.docx`, `.xlsx`, `.pptx`). Zawartość binarna jest przesyłana zakodowana base64. * `sourceUrl` staje się linkiem "przejdź do źródła" przy każdym cytowaniu dokumentu. Pomiń go przy ponownym przesłaniu, aby zachować zapisany, lub wyślij `null`, aby go wyczyścić. * `type` ustawia `content_type` dokumentu, według którego przeszukiwanie i filtrowanie listy są filtrowane. Całe ciało żądania jest ograniczone do 1 MB, więc duży plik lub duża partia odpowiada `413`; podziel ją. ## Wybierz, kto może go przeczytać [#wybierz-kto-może-go-przeczytać] `permissions` jest wymagane przy każdym przesłaniu, więc decyzja o udostępnieniu nigdy nie jest podejmowana przez pominięcie pola. W źródle danych widocznym dla przestrzeni roboczej: | `permissions` | Kto może przeczytać dokument | | ----------------------------------------- | -------------------------------------------------------------------- | | `{}` | Każdy członek przestrzeni roboczej | | `{ "allowedUsers": ["ana@example.com"] }` | Tylko wymienione osoby | | `{ "allowedGroups": ["GROUP_ID"] }` | Członkowie tych grup przestrzeni roboczej, w tym grup zagnieżdżonych | | `{ "allowAllTenantMembers": false }` | Odrzucane: dokument, którego nikt nie może przeczytać, jest usuwany | Aby zmienić, kto może przeczytać dokument bez ponownego wysyłania jego treści, użyj `POST /documents/push/permissions`. Udostępnienie dokumentu już ograniczonego całej przestrzeni roboczej wymaga dodatkowo zakresu `index:acl-widen`, więc rutynowa synchronizacja nie może potajemnie cofnąć ograniczenia ustawionego ręcznie. ## Prześlij w partiach [#prześlij-w-partiach] `/documents/push/bulk` przyjmuje do 100 dokumentów dla jednego źródła danych na jedno wywołanie. Odpowiedź zlicza `accepted` i `rejected` i podaje wynik dla każdego dokumentu, więc jeden zły dokument nie powoduje niepowodzenia całej partii. Limit 1 MB na ciało żądania obowiązuje na jedno wywołanie, więc podziel duże przesyłki na kilka wywołań z tym samym `uploadId`. ```bash curl https://nordvec.com/api/v1/documents/push/bulk \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "uploadId": "nightly-2026-09-28", "datasource": "confluence-export", "documents": [ { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/plain", "content": "..." }, "permissions": {} } ] }' ``` ## Zastąp całe źródło danych [#zastąp-całe-źródło-danych] Gdy twój system może wyświetlić pełną listę dokumentów, które powinno zawierać źródło danych, wyślij całą listę jako jedną **sesję przesyłania**. Dokumenty, których nie ma już na liście, zostaną przeniesione do kosza po zamknięciu sesji. Sesje wymagają klucza API do indeksowania z uprawnieniami `index:delete` oraz `index:write`, ponieważ zamknięcie sesji usuwa dokumenty. Tylko klucz, który ją otworzył, może ją kontynuować. 1. Wyślij pierwszą stronę z `"isFirstPage": true`. To strona `0`. 2. Wyślij każdą kolejną stronę z jej `pageIndex` (`1`, `2`, ...), w dowolnej kolejności. Strona wysłana dwukrotnie jest liczona raz, więc ponowienie jest zawsze bezpieczne. 3. Wyślij ostatnią stronę z `"isLastPage": true` i jej `pageIndex`. Lista, która mieści się na jednej stronie, wysyła `isFirstPage` i `isLastPage` razem. Ostatnia strona może nie zawierać dokumentów. Każda strona używa tego samego `uploadId`, a każda odpowiedź zawiera postęp sesji w polu `upload`. Sesja zamyka się dopiero po otrzymaniu wszystkich stron od `0` do ostatniej. Zamknięcie sesji przenosi do kosza każdy dokument ze źródła danych, który nie został wymieniony w żadnej stronie sesji i istniał przed jej otwarciem. Każde inne żądanie push do źródła danych podczas trwania sesji zachowuje dokument, który wskazuje: pojedyncze żądanie push, wsad bez pól sesji, aktualizację uprawnień czy ponowne przesłanie niezmienionej treści. Kosz przechowuje usunięte dokumenty przez 30 dni. Ponowne przesłanie dokumentu przywraca go, podobnie jak przywrócenie całej sesji (patrz poniżej). Sesja, która nie otrzyma żadnej strony przez 24 godziny, wygasa i zamyka się bez usuwania czegokolwiek. Odrzucona strona otrzymuje odpowiedź z `409 Conflict`, nic nie zapisuje, a jej `data.reason` wyjaśnia przyczynę: | `reason` | Co zrobić | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `upload_incomplete` | Wyślij strony wymienione w `missingPageIndexes`, a następnie ponownie ostatnią stronę | | `deletion_confirmation_required` | Zamknięcie sesji usunęłoby ponad 20% źródła danych. Jeśli to poprawne, wyślij ostatnią stronę ponownie z `"confirmDeletions"` ustawionym na `wouldTombstone` | | `deletion_confirmation_too_large` | `confirmDeletions` jest większe niż liczba dokumentów, które źródło danych zawierało w momencie otwarcia sesji. Wyślij oczekiwaną liczbę dokumentów do usunięcia | | `upload_in_progress` | Na tym źródle danych trwa inna sesja. Jeśli należy do twojego klucza, zakończ ją, poczekaj na jej wygaśnięcie lub rozpocznij od nowa z `"forceRestartUpload": true` w pierwszej stronie. Jeśli otworzył ją inny klucz, `forceRestartUpload` zastąpi ją dopiero po godzinie braku aktywności, od czasu podanego w `restartableAt` | | `upload_expired`, `upload_missing`, `upload_restarted` | Sesja została usunięta. Rozpocznij nową z nowym `uploadId` | | `upload_closed`, `upload_id_reused` | `uploadId` został wykorzystany. Użyj nowego | | `page_index_required` | Twój klucz ma otwartą sesję na tym źródle danych. Wyślij `pageIndex` wraz ze stroną | Aby wznowić po awarii, odczytaj sesję za pomocą `GET /documents/push/upload?tenantId=...&datasource=...&uploadId=...` (zakres `index:status`). Jej `missingPageIndexes` zawiera listę stron, które nadal trzeba wysłać. ### Cofnij zamknięcie sesji [#cofnij-zamknięcie-sesji] Jeśli sesja usunęła dokumenty, których nie powinna, na przykład dlatego, że przesłana lista była niekompletna, przywróć je jednym wywołaniem: ```bash curl https://nordvec.com/api/v1/documents/push/upload/restore \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "datasource": "confluence-export", "uploadId": "nightly-2026-09-28" }' ``` Klucz, który otworzył sesję, może ją przywrócić, podobnie jak administrator przestrzeni roboczej zalogowany do Nordvec, w przypadku sesji otwartej przez dowolny klucz. Każdy dokument, który zamknięcie przeniosło do kosza, wraca z treścią, jaką miał, a odpowiedź zlicza je: `restored` są ponownie aktywne, `purged` zostały już trwale usunięte przez kosz, a `skipped` zmieniły się od czasu zamknięcia (zostały ponownie przesłane lub usunięte) i pozostały w obecnym stanie. Przywrócenie sesji po raz drugi odpowiada zliczeniami z pierwszego przywrócenia i `"replayed": true`, a także kolejkuje każdy przywrócony dokument, który nadal czeka na indeksowanie, więc powtórzenie przywracania, które nie zakończyło się odpowiedzią, jest bezpieczne. Sesję można przywrócić w ciągu 35 dni od jej zamknięcia oraz tak długo, jak kosz nadal przechowuje jakikolwiek dokument, który usunęła. Odmowa przywrócenia jest sygnalizowana odpowiedzią `409 Conflict` i jej `data.reason`: | `reason` | Co to oznacza | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `upload_not_closed` | Sesja nigdy nie została zamknięta, więc nic nie usunęła | | `upload_in_progress` | Sesja jest otwarta na źródle danych. Przywróć ją po zamknięciu lub wygaśnięciu | | `restore_purged` | Minęło ponad 30 dni, a kosz usunął wszystkie dokumenty. Prześlij je ponownie | | `workspace_not_entitled` | Plan przestrzeni roboczej nie pozwala obecnie na przywracanie z kosza | | `corpus_cap_exceeded` | Przywrócenie dokumentów przekroczyłoby limit dokumentów przestrzeni roboczej, więc żaden nie wrócił. `data.wouldRestore` to liczba potrzebnych miejsc, a `data.headroom` to liczba dostępnych miejsc. Zwolnij miejsce, a następnie spróbuj przywrócić ponownie | ## Śledź ingestię [#śledź-ingestię] Przesłanie odpowiada, gdy tylko dokument zostanie zakolejkowany. Sprawdź jego postęp za pomocą `GET /documents/push/status` (zakres `index:status`), filtrowanego według źródła danych lub identyfikatora dokumentu. Dokument przechodzi ze stanu `queued` przez `processing` do `completed` lub do `failed` z `error`. ## Gdy przesłanie jest odrzucane [#gdy-przesłanie-jest-odrzucane] Przesłanie, które wskazuje nieznane lub wstrzymane źródło danych, jest odrzucane z odpowiedzią `422 Unprocessable Content`. Wiadomość zawiera slug i link do **Ustawienia przestrzeni roboczej > Źródła danych** w Twojej przestrzeni roboczej, a `data` błędu mówi, dlaczego i co zrobić: ```json { "defined": true, "code": "UNPROCESSABLE_CONTENT", "status": 422, "message": "Datasource \"confluence-export\" is paused and accepts no documents. A workspace admin resumes it under Workspace settings > Datasources: https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources", "data": { "why": "The datasource \"confluence-export\" is paused", "fix": "Resume it at https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources, then retry the push", "link": "https://nordvec.com/docs/guides/how-to/push-documents" } } ``` Nie ponawiaj tych automatycznie: udają się tylko po tym, jak administrator utworzy lub wznowi źródło danych. ## Usuń dokument [#usuń-dokument] `POST /documents/push/delete` (zakres `index:delete`) usuwa wypchnięty dokument za pomocą jego `datasource` i `id`. Dokumenty, których przestajesz wypychać, nie są usuwane automatycznie: usuń każdy, który wycofujesz, lub wyślij pełną listę źródła danych jako sesję przesyłania, jak opisano powyżej. ## Wstrzymaj, wznów i usuń [#wstrzymaj-wznów-i-usuń] * **Wstrzymaj** odrzuca każde dalsze przesłanie do źródła danych. Jego dokumenty pozostają przeszukiwalne. Przesłanie już zapisywane w momencie wstrzymania zostanie ukończone. * **Wznów** ponownie akceptuje przesłania. * **Usuń** usuwa źródło danych i każdy przesłany do niego dokument, wraz z ich indeksem wyszukiwania. Twój własny system zachowuje swoją kopię, więc ponowne przesłanie po odtworzeniu źródła danych przywraca je. Usunięcia nie można cofnąć. Jeśli inny administrator zmienił źródło danych po załadowaniu Twojej listy, akcja jest odrzucana, a lista jest ponownie ładowana, więc decydujesz ponownie na podstawie tego, co jest teraz. Każde utworzenie, wstrzymanie, wznowienie i usunięcie jest rejestrowane w dzienniku audytu przestrzeni roboczej. Lista ustawień pokazuje, komu widoczne jest każde źródło danych. Kto może przeczytać przesłany dokument, decyduje `permissions` przesłany wraz z nim; tworzenie, wstrzymywanie lub usuwanie źródła danych nigdy nie poszerza dostępu do niczego. Zapisy push są idempotentne: powtórz to samo `Idempotency-Key` przy każdej próbie jednego zapisu, a duplikat jest odpowiadany z pierwszej próby zamiast być stosowany dwukrotnie. Zobacz [Błędy i limity szybkości](/docs/guides/errors-and-rate-limits). ## Następne kroki [#następne-kroki] --- # Filtrowanie i precyzowanie wyszukiwania Source: https://nordvec.com/pl/docs/guides/how-to/filter-search Ogranicz wyszukiwanie dokumentów za pomocą filtrów źródła danych, dostawcy, typu i daty, a następnie odczytaj wyniki uszeregowane według trafności. `/documents/search` przeszukuje pełny tekst tytułu i całej treści twoich dokumentów i zwraca najlepsze trafienia, każde z wynikiem trafności oraz dokumentem źródłowym, z którego pochodzi. Ten przewodnik pokazuje, jak zapytanie jest dopasowywane, jak zawężać wyniki za pomocą filtrów oraz jak odczytywać odpowiedź. ## Żądanie [#żądanie] Tylko `query` jest wymagane. Wszystko inne zawęża lub ogranicza wyniki. ```bash curl https://nordvec.com/api/v1/documents/search \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "renewal terms", "limit": 20, "datasource": "contracts", "sourceProvider": "google", "createdAfter": "2026-01-01T00:00:00Z", "createdBefore": "2026-07-01T00:00:00Z" }' ``` | Pole | Typ | Uwagi | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Wymagane. Od 1 do 500 znaków. Rozumiane są frazy w cudzysłowach, `or` oraz znak `-` na początku, aby wykluczyć słowo. | | `limit` | integer | Opcjonalne. Od 1 do 50, domyślnie 20. Określa, ile wyników zwrócić. | | `datasource` | string | Opcjonalne. Ogranicza wyniki do jednego źródła danych po jego slugu (do 200 znaków). | | `sourceProvider` | string | Opcjonalne. Ogranicza wyniki do jednego dostawcy łącznika, na przykład `google`, `sharepoint` lub `slack`. | | `createdAfter` | string | Opcjonalne. Znacznik czasu ISO 8601 z przesunięciem; tylko dokumenty utworzone w tym czasie lub później. | | `createdBefore` | string | Opcjonalne. Znacznik czasu ISO 8601 z przesunięciem; tylko dokumenty utworzone w tym czasie lub wcześniej. | | `contentType` | string | Opcjonalne. Ogranicza wyniki do jednego typu wiedzy, który deklaruje `type` przesłanego dokumentu lub plik wiedzy (na przykład `policy` lub `runbook`). | Każdy filtr jest łączony za pomocą AND: dokument musi pasować do zapytania **oraz** każdego filtru, który podasz. Pomiń filtr, aby poszerzyć wyszukiwanie. ## Jak zapytanie jest dopasowywane [#jak-zapytanie-jest-dopasowywane] * **Przeszukiwany jest cały dokument.** Liczy się tytuł i każdy fragment tekstu, niezależnie od długości dokumentu. * **Słowa pasują w formie, w jakiej je wpiszesz, w każdym języku.** Nie ma stemmingu: `invoice` nie pasuje do `invoices`, a `tilbagebetaling` nie pasuje do `tilbagebetalingen`. Aby uchwycić kilka form, połącz je za pomocą `or`. * **Znaki diakrytyczne są ignorowane po obu stronach.** `cafe` znajduje `café`, a `børnehave` i `bornehave` znajdują się nawzajem. Wielkość liter jest również ignorowana. * **Operatory.** Umieść słowa w podwójnym cudzysłowie, aby dopasować je jako frazę, wpisz `or` między słowami, aby dopasować jedno z nich, a przed słowem umieść `-`, aby wykluczyć dokumenty, które je zawierają. ## Wypróbuj [#wypróbuj] Po zalogowaniu możesz przeszukać swoje dokumenty bezpośrednio z tej strony. Zmień zapytanie w dokumentacji API, aby wypróbować własne. Try it in the API reference: [`POST /api/v1/documents/search`](https://nordvec.com/docs/api#tag/documents/POST/documents/search) (Search documents). ## Odpowiedź [#odpowiedź] ```json { "results": [ { "id": "0198f2a4-6c1e-7d30-b6a1-2f9d54c08a11", "title": "Acme Corp Master Services Agreement", "snippet": "Automatic **renewal**: the agreement continues for successive twelve month **terms** unless…", "score": 0.82, "datasource": "contracts", "source_provider": "google", "source_type": null, "mime_type": "application/pdf", "content_type": null, "status": "indexed", "created_at": "2026-02-14T09:00:00Z", "updated_at": "2026-02-14T09:00:00Z" } ], "totalCount": 7 } ``` Każdy wynik to jeden dokument. Jego `snippet` jest wycięty z fragmentu, który najlepiej pasował, niezależnie od miejsca w tekście, a dopasowane słowa są otoczone znacznikami `**`. Słowo, które wpisałeś bez znaków diakrytycznych, zostanie znalezione i ocenione, ale może pojawić się w podglądzie bez oznaczenia. `score` mieści się w zakresie od 0 do, ale nie osiągając, 1 (wyższa wartość oznacza większą trafność), a metadane dokumentu źródłowego pozwalają prześledzić wynik. `totalCount` to całkowita liczba dokumentów, które pasowały, co może być większe niż liczba `results`, o którą poprosiłeś za pomocą `limit`. ## Odczytywanie wyników [#odczytywanie-wyników] * **Wyniki są uszeregowane według trafności**, najbardziej trafne jako pierwsze. Dokument jest oceniany na podstawie najlepiej pasującego fragmentu. Użyj `score`, aby odrzucić słabe trafienia w jednym zestawie wyników; wyniki z różnych zapytań nie są porównywalne. * **`totalCount` a `results.length`**: `results` zawiera do `limit` elementów; `totalCount` to pełna liczba dopasowań. Jeśli `totalCount` jest znacznie większe niż twoje `limit`, zaostrz `query` lub dodaj filtr; nie ma drugiej strony wyników wyszukiwania. * **`status` informuje, na jakim etapie przetwarzania znajduje się dokument.** Dokument jest dopasowywany na podstawie przechowywanego tekstu, więc taki, który jest jeszcze `processing`, może się pojawić; `indexed` oznacza, że każdy krok został zakończony. Zobacz [Dokumenty i wyszukiwanie](/docs/guides/concepts/documents), aby poznać cykl życia. Wyszukiwanie zwraca tylko dokumenty, które osoba wywołująca ma prawo zobaczyć. Kontrola dostępu jest egzekwowana w bazie danych, a nie w kodzie aplikacji, więc filtr nigdy nie poszerzy tego, co widzi osoba wywołująca. Dla klucza API jest to to, co udostępnia przestrzeń robocza; zobacz [Kto widzi dokument](/docs/guides/concepts/documents#who-sees-a-document). ## Następne kroki [#następne-kroki] --- # Przeglądaj i pobieraj dokumenty Source: https://nordvec.com/pl/docs/guides/how-to/list-documents Przeglądaj swoje dokumenty za pomocą paginacji kursorowej, filtruj i sortuj je, a także pobierz jeden lub wiele po identyfikatorze. Gdy [wyszukiwanie](/docs/guides/how-to/filter-search) szereguje dokumenty według trafności do zapytania, listing przegląda cały korpus w określonej kolejności. Użyj go do synchronizacji, audytu lub zbudowania własnego indeksu nad tym, co przechowuje Nordvec. Listing zwraca tylko metadane, bez treści dokumentów. ## Listing z kursorową paginacją [#listing-z-kursorową-paginacją] `/documents/list` zwraca stronę dokumentów oraz nieprzezroczysty `nextCursor`. Przekaż ten kursor z powrotem, aby uzyskać kolejną stronę, i zakończ, gdy `hasMore` będzie `false`. ```bash curl "https://nordvec.com/api/v1/documents/list?limit=50" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` ```json { "items": [ { "id": "…", "title": "Q3 Financial Report", "status": "indexed", "datasource": "finance", "created_at": "2026-04-01T10:00:00Z" } ], "nextCursor": "eyJrIjoi…", "hasMore": true } ``` Po zalogowaniu możesz wyświetlić pierwszą stronę swoich dokumentów stąd: Try it in the API reference: [`GET /api/v1/documents/list`](https://nordvec.com/docs/api#tag/documents/GET/documents/list) (List documents). Aby przejść przez wszystkie strony, wykonuj pętlę, aż `hasMore` będzie `false`, przekazując za każdym razem `nextCursor` z poprzedniej odpowiedzi, z tym samym `sort` i `direction`: ```bash curl "https://nordvec.com/api/v1/documents/list?limit=50&cursor=eyJrIjoi…" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` Kursor jest nieprzezroczysty, nie analizuj go ani nie konstruuj. Przekazuj dokładnie to, co zwróciła poprzednia odpowiedź. Nieprawidłowy kursor lub taki z innej kolejności sortowania zostanie odrzucony. ## Filtrowanie i sortowanie [#filtrowanie-i-sortowanie] Wszystkie filtry są opcjonalne i łączone za pomocą AND. Sortowanie domyślnie ustawione jest na od najnowszych. | Pole | Typ | Uwagi | | -------------------------------- | ------- | ------------------------------------------------------------------------ | | `limit` | integer | 1 do 200 (domyślnie 50). | | `cursor` | string | Nieprzezroczysty kursor z poprzedniej strony. | | `datasource` | string | Ogranicz do jednego źródła danych po jego slugu (do 200 znaków). | | `status` | enum | `indexed`, `processing` lub `failed`. | | `sourceProvider` | string | Ogranicz do jednego dostawcy łącznika, na przykład `google` lub `slack`. | | `contentType` | string | Ogranicz do jednego typu wiedzy, na przykład `policy` lub `runbook`. | | `createdAfter` / `createdBefore` | string | Znaczniki czasu ISO 8601 z przesunięciem, oba włącznie. | | `sort` | enum | `createdAt` (domyślnie), `updatedAt` lub `title`. | | `direction` | enum | `desc` (domyślnie) lub `asc`. | ```bash curl "https://nordvec.com/api/v1/documents/list?status=indexed&datasource=finance&sort=updatedAt&direction=desc&limit=100" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` ### Które sortowanie wybrać do przeglądania [#które-sortowanie-wybrać-do-przeglądania] * **Pełna, jednorazowa enumeracja**: `sort=createdAt`. Czas utworzenia nigdy się nie zmienia, więc każdy dokument pojawi się dokładnie raz. * **Inkrementalna aktualizacja od punktu odniesienia**: `sort=updatedAt&direction=asc`. Dokument zaktualizowany podczas przeglądania może pojawić się dwukrotnie, więc wykonaj upsert według `id`. * **Kolejność wyświetlania**: `updatedAt` lub `title` malejąco. Dokument zaktualizowany między dwiema stronami może przesunąć się za kursor i zostać pominięty, więc nie używaj tego do enumeracji. ## Pobieranie pojedynczego dokumentu [#pobieranie-pojedynczego-dokumentu] `/documents/{id}` zwraca metadane, stan przetwarzania i tekst jednego dokumentu. Długi tekst można odczytywać w oknach: `contentOffset` i `contentMaxChars` (liczone w jednostkach kodowych UTF-16) wybierają jedno okno, a `content_range` informuje o oknie i pełnej długości, więc czytaj dalej, aż `offset + length` osiągnie `total`. ```bash curl "https://nordvec.com/api/v1/documents/DOCUMENT_ID?contentMaxChars=100000" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` ## Pobieranie wielu naraz [#pobieranie-wielu-naraz] Aby rozpoznać do 200 identyfikatorów w jednym wywołaniu, wyślij je metodą POST do `/documents/batch` zamiast wykonywać jedno żądanie na identyfikator. Partia zwraca metadane i stan przetwarzania; `content` jest zawsze `null`, więc odczytaj tekst za pomocą wywołania dla pojedynczego dokumentu. ```bash curl https://nordvec.com/api/v1/documents/batch \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ids": ["DOCUMENT_ID_1", "DOCUMENT_ID_2"] }' ``` Listing, podobnie jak wyszukiwanie, zwraca tylko dokumenty, które wywołujący może zobaczyć. `status` informuje, na jakim etapie przetwarzania znajduje się dokument: `processing`, gdy jest nadal indeksowany, `failed`, gdy nie udało się go przetworzyć. Zobacz [Dokumenty i wyszukiwanie](/docs/guides/concepts/documents), aby poznać cykl życia. ## Następne kroki [#następne-kroki]