# useDocyrusDataExport
URL: /docs/web/hooks/use-docyrus-data-export

Server-side export for Docyrus data sources — POSTs a query payload to the export edge function and streams the result file straight to the browser.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-export
```

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)

This hook is distributed as source. It needs an authenticated `RestApiClient` from `@docyrus/api-client` somewhere above your component tree.

## Overview

`useDocyrusDataExport` wraps the Docyrus server-side export endpoint (`POST /v1/edge/run/query-export`). The server applies the same filters, search, and column projection used by the items query and streams back a binary file (xlsx by default). `RestApiClient.download()` then writes it to the user's browser using the `Content-Disposition` filename.

Use this hook when:

- The export needs to cover more rows than the grid currently has loaded.
- You want the canonical, server-authored xlsx (with formatting, formula columns, lookups resolved).
- You want filters, search, and column visibility to round-trip exactly as the user sees them.

For exports of an already-loaded array of rows (no server round-trip, four formats including JSON and Markdown), use [`useDataExport`](/docs/web/hooks/use-data-export) instead.

| Hook | Where serialization happens | Formats | Best for |
|------|-----------------------------|---------|----------|
| [`useDataExport`](/docs/web/hooks/use-data-export) | Client | csv, json, markdown, xlsx | In-memory rows, custom columns, selection-only exports |
| `useDocyrusDataExport` | Server (edge function) | xlsx (default), csv | Full data source, large exports, canonical Docyrus output |

## Usage

### Basic example

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { Button } from '@docyrus/ui/primitives/ui/button';
import { useDocyrusDataExport } from '@docyrus/ui/library/hooks/use-docyrus-data-export';

export function ExportContactsButton({ dataSourceId }: { dataSourceId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const { exportData, isExporting, error } = useDocyrusDataExport({ client });

  return (
    <>
      
      {error ? <p className="text-destructive">{error.message}</p> : null}
    </>
  );
}
```

With no extra payload fields, the server defaults apply: every exportable column, no filters, the hook's `defaultLimit` (10 000 rows), and xlsx output.

### Mirroring the visible grid

Pair the hook with [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) so the export reflects exactly what the user sees — same filters, same search, same column visibility:

```tsx
const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
const { exportData, isExporting } = useDocyrusDataExport({ client });

async function handleExport() {
  await exportData({
    dataSourceId: grid.dataSourceId,
    columns: grid.visibleColumnSlugs, // visible-only, in display order
    filters: grid.filterGroup,
    filterKeyword: grid.search,
    limit: 50000
  });
}
```

### Free-form extras (server-controlled fields)

Any unknown keys on the payload are forwarded verbatim. Use this for tenant-specific fields the server understands without changing the hook:

```tsx
await exportData({
  dataSourceId,
  columns: ['name', 'email', 'createdOn'],
  format: 'csv',
  // forwarded as-is
  timezone: 'Europe/Istanbul',
  locale: 'tr-TR'
});
```

### Override the endpoint

```tsx
const { exportData } = useDocyrusDataExport({
  client,
  endpoint: '/v1/edge/run/tenant-export',
  defaultLimit: 25000
});
```

Override only when a deployment exposes the export edge function under a non-standard route.

## API Reference

### Parameters — `UseDocyrusDataExportOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated REST client used to POST the export request. **Required.** |
| `defaultLimit` | `number` | `10000` | Default row cap when `payload.limit` is omitted. |
| `endpoint` | `string` | `'/v1/edge/run/query-export'` | Endpoint path. Override only when a deployment exposes the export edge function under a different route. |

### `exportData(payload)` — `DocyrusDataExportPayload`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `dataSourceId` | `string` | — | Target data source ID — required by the edge query. **Required.** |
| `columns` | `'*' \| ReadonlyArray<string>` | `'*'` | Columns to include. Pass `'*'` (or omit) to let the server default to every exportable field, or an array of field slugs to project a specific subset. |
| `filters` | `RuleGroupType \| null` | `null` | Filter group applied to the underlying items query. Pass the same shape used by the items endpoint (combinator + rules). Empty rule groups are normalised to `null` server-side. |
| `filterKeyword` | `string` | — | Free-text keyword search forwarded to the server. Omitted from the request body when empty. |
| `limit` | `number` | `defaultLimit` | Maximum number of rows to export. Falls back to `defaultLimit` when omitted or non-positive. |
| `format` | `'xlsx' \| 'csv'` | `'xlsx'` | Optional override for the export format. Final format is server-controlled. |
| `[key: string]` | `unknown` | — | Free-form extras forwarded verbatim to the endpoint. |

### Return Value — `UseDocyrusDataExportResult`

| Property | Type | Description |
|----------|------|-------------|
| `exportData` | `(payload: DocyrusDataExportPayload) => Promise<void>` | Trigger a server-side export. Resolves once the file has been streamed to the browser; rejects with the original error (which is also stored in `error`). |
| `isExporting` | `boolean` | `true` while a request is in flight. Use it to disable the trigger button. |
| `error` | `Error \| null` | Last error thrown by `exportData`. Cleared on every new attempt. |

### Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusDataExportOptions` | Hook input (`client`, `defaultLimit`, `endpoint`). |
| `UseDocyrusDataExportResult` | Hook return value (`exportData`, `isExporting`, `error`). |
| `DocyrusDataExportPayload` | Body shape POSTed to the export endpoint. Includes the index signature for forwarding extras. |

## Backend connection

| Method | Endpoint | Purpose |
|--------|----------|---------|
| `POST` | `/v1/edge/run/query-export` | Server reads the payload, applies filters/search/column projection, and streams back a binary file (xlsx by default). The browser saves it using the `Content-Disposition` filename. |

The endpoint can be overridden via the `endpoint` option when a deployment exposes the export edge function under a different route.

## Notes

- Empty filter groups (`{ combinator: 'and', rules: [] }`) are normalised to `null` before the request leaves the client so the server query plan stays clean.
- `client.download()` handles the binary response: it reads the `Content-Disposition` filename, builds a `Blob`, and triggers the download via a temporary `<a download>` element.
- Errors are stored on `error` and re-thrown from `exportData()` so callers can `await` and catch (or rely on the state).
- This hook does **not** project rows or own a column UI — pair it with [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) (or any source of `dataSourceId` + filter group) to drive the payload.