> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroentropy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Engine

> Using `zsearch`, the search engine developed by ZeroEntropy

## zsearch

`zsearch` is ZeroEntropy's end-to-end search engine, abstracting away data processing from OCR and chunking, to embedding and storing, to querying and reranking.

## Index

#### Add documents to a collection

When you add a document to a collection in `zsearch`, it goes through a fully managed ingestion pipeline:

1. **Parse:** Binary files (PDF, DOCX, PPT, images, etc.) are OCR'd and converted to text. Plain text and CSV inputs skip this step.
2. **Chunk:** The parsed text is split into chunks at multiple granularities: coarse (\~2000 chars) and fine (\~200 chars), optimized for retrieval.
3. **Embed:** Each chunk is embedded using `zembed-1`, ZeroEntropy's state-of-the-art multilingual embedding model, and stored in our vector index.

When you call [add-document](/api-reference/documents/add-document), documents are automatically added to a collection with a unique path (like a filepath). ZeroEntropy supports three content types:

* `text`: Plain text content.
* `text-pages` / `text-pages-unordered`: Pre-paginated text (array of strings). Use unordered for data like CSVs where pages are independent.
* `auto`: Binary files (PDF, DOCX, PPT, etc.) encoded as base64. ZeroEntropy handles OCR and parsing automatically.

Set `overwrite: true` to upsert (atomically replace if the path already exists).

#### Custom Chunking

If you want control over how your data is chunked, use the `text-pages` content type. Each string in the pages array becomes its own page in the index, letting you define chunk boundaries yourself. Use `text-pages-unordered` when pages are independent (e.g. CSV rows, FAQ entries).
See [examples](/examples/upload) for detailed walkthroughs of different ingestion strategies.

#### Using zembed-1 as a standalone

You can also call `zembed-1` directly via the [embed endpoint](/api-reference/models/embed) and plug it in to a vector database of your choice. See [Models](/models) for more details.

## Query

There are three granularity levels for querying your indexed data: documents, pages, and snippets. All query endpoints accept a natural language query, a collection\_name, and a `k` parameter controlling how many results to return.
All query endpoints support [metadata filtering](/metadata-filtering) via the optional `filter` parameter.

#### Top Documents

Returns the top K most relevant documents for a given query. Useful when you want to identify which documents are relevant without needing sub-document granularity.

Note that `top-documents` only returns document paths, not contents. Document contents are accessible using the [Get Document Info endpoint](/api-reference/documents/get-document-info).
Use latency\_mode: "high" if you need higher throughput at the cost of higher latency (default is "low").

<CodeGroup>
  ```python Python theme={null}
  from zeroentropy import ZeroEntropy
  zclient = ZeroEntropy()

  response = zclient.queries.top_documents(
      collection_name="contracts",
      query="What are the payment terms?",
      k=5,
      include_metadata=True,
  )
  ```

  ```javascript Javascript theme={null}
  import ZeroEntropy from 'zeroentropy';
  const zclient = new ZeroEntropy();

  const response = await zclient.queries.topDocuments({
      collection_name: "contracts",
      query: "What are the payment terms?",
      k: 5,
      include_metadata: true,
      reranker: "zerank-2",  // optional
  });

  for (const doc of response.results) {
      console.log(`${doc.path} (score: ${doc.score})`);
  }
  ```
</CodeGroup>

#### Top Pages

Returns the top K most relevant pages. Ideal for page-level retrieval over PDFs, DOCX, or documents ingested with text-pages content type. \
Set include\_content to true to return the full text of each page. A **URL to an image** of the page will also be provided in the results.

#### Top Snippets

Returns the top K most relevant text snippets. This is the most granular query type. \
Each snippet includes the exact character range (start\_index, end\_index) and page\_span within the source document.\
You can choose between coarse snippets (averaging \~2000 characters, default) and precise snippets (averaging \~200 characters) using the precise\_responses parameter. \
Pass a reranker, such as `zerank-2` for even better ranking.

<CodeGroup>
  ```python Python theme={null}
  from zeroentropy import ZeroEntropy
  zclient = ZeroEntropy()
  response = zclient.queries.top_snippets(
  collection_name="pdfs",
  query="What is Retrieval Augmented Generation?",
  k=10,
  reranker="zerank-2",
  precise_responses=True,
  )
  for snippet in response.results:
  print(f"{snippet.path} [pages {snippet.page_span}] (score: {snippet.score})")
  print(snippet.content)
  ```

  ```javascript Javascript theme={null}
  import ZeroEntropy from 'zeroentropy';
  const zclient = new ZeroEntropy();

  const response = await zclient.queries.topSnippets({
      collection_name: "pdfs",
      query: "What is Retrieval Augmented Generation?",
      k: 10,
      reranker: "zerank-2",
      precise_responses: true,
  });

  for (const snippet of response.results) {
      console.log(`${snippet.path} [pages ${snippet.page_span}] (score: ${snippet.score})`);
      console.log(snippet.content);
  }
  ```
</CodeGroup>

## Data Management

zsearch organizes data into collections, each containing documents. Think of collections as databases and documents as records.

#### Collections

Create, list, and delete collections. Collection names are strings up to 1024 UTF-8 bytes.

<CodeGroup>
  ```python Python theme={null}
  from zeroentropy import ZeroEntropy
  zclient = ZeroEntropy()
  # Create a collection
  zclient.collections.add(collection_name="contracts")
  # List all collections
  response = zclient.collections.get_list()
  print(response.collection_names)
  # Delete a collection
  zclient.collections.delete(collection_name="contracts")
  ```

  ```javascript Javascript theme={null}
  import ZeroEntropy from 'zeroentropy';
  const zclient = new ZeroEntropy();

  // Create a collection
  await zclient.collections.add({ collection_name: "contracts" });

  // List all collections
  const response = await zclient.collections.getList();
  console.log(response.collection_names);

  // Delete a collection
  await zclient.collections.delete({ collection_name: "contracts" });
  ```
</CodeGroup>

#### Documents

After adding a document to a collection, it takes time to parse and index.
Use the [Get Document Info](/api-reference/documents/get-document-info) endpoint to track progress. \\

Each document response includes file\_url for downloading the raw file, index\_status for tracking processing state, raw content, and num\_pages (null if still parsing or unsupported filetype). \\

You can delete one or more documents by path. We support batch deletion of up to 64 paths at once.

<CodeGroup>
  ```python Python theme={null}
  from zeroentropy import ZeroEntropy
  zclient = ZeroEntropy()
  # Delete a single document
  zclient.documents.delete(
  collection_name="contracts",
  path="contracts/acme-nda.txt",
  )
  # Batch delete
  response = zclient.documents.delete(
  collection_name="contracts",
  path=["old/doc1.txt", "old/doc2.txt", "old/doc3.txt"],
  )
  print(response.deleted_paths)  # paths that were actually found and deleted
  ```

  ```javascript Javascript theme={null}
  import ZeroEntropy from 'zeroentropy';
  const zclient = new ZeroEntropy();

  // Delete a single document
  await zclient.documents.delete({
      collection_name: "contracts",
      path: "contracts/acme-nda.txt",
  });

  // Batch delete
  const response = await zclient.documents.delete({
      collection_name: "contracts",
      path: ["old/doc1.txt", "old/doc2.txt", "old/doc3.txt"],
  });
  console.log(response.deleted_paths);
  ```
</CodeGroup>

More examples can be found [here](/examples/setup).