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

Server-side export of a Docyrus data source on React Native. POSTs the column list, filters and keyword to the query-export endpoint, writes the returned xlsx or csv file into the cache directory and opens the share sheet.

## Installation

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

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@react-querybuilder/core](https://www.npmjs.com/package/@react-querybuilder/core)
- [expo-file-system (optional)](https://www.npmjs.com/package/expo-file-system)
- [expo-sharing (optional)](https://www.npmjs.com/package/expo-sharing)

The hook needs an authenticated `RestApiClient`. Unlike [`useDataExport`](/docs/native/hooks/use-data-export), which projects rows you already loaded, the server runs the full query and streams back the whole result set as a file. Pair it with [rn-docyrus-data-export-menu](/docs/native/docyrus/docyrus-data-export-menu) for the column picker.

`expo-file-system` and `expo-sharing` are **optional peers**, loaded lazily through the internal `lib/native-export` helpers. Without `expo-file-system`, `exportData` resolves `null`. Without `expo-sharing`, the file is written but not shared.

## Usage

```tsx
import { useDocyrusClient } from '@docyrus/signin/react-native';

import { Button } from '@/components/docyrus-native/button';
import { useDocyrusDataExport } from '@/hooks/docyrus-native/use-docyrus-data-export';

export function ExportTasks({ dataSourceId, query, keyword }: Props) {
  const client = useDocyrusClient();
  const { exportData, isExporting, error } = useDocyrusDataExport({
    client: client!,
    fileName: 'tasks'
  });

  return (
    
  );
}
```

### Request body

`exportData(payload)` sends `POST /v1/edge/run/query-export` (or `endpoint`) with `responseType: 'arrayBuffer'` and this body:

| Key | Value |
|-----|-------|
| `dataSourceId` | From the payload. |
| `columns` | `'*'` when omitted, `'*'` or empty. Otherwise the slugs joined with `,` (inline projections such as `country(id,name)` are kept). |
| `filters` | The `RuleGroupType`, or `null` when it has no rules. |
| `limit` | `payload.limit` when it is a positive number, otherwise `defaultLimit`. |
| `filterKeyword` | Only sent when non-empty. |
| any other key | Forwarded as is (for example `format`). |

The response bytes are written to `<cache>/<fileName>.xlsx` (or `.csv` when `payload.format === 'csv'`) and handed to the share sheet. Errors are stored in `error` and re-thrown.

## API Reference

### Options (`UseDocyrusDataExportOptions`)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated REST client (required). |
| `defaultLimit` | `number` | `10000` | Row cap when `payload.limit` is omitted. |
| `endpoint` | `string` | `'/v1/edge/run/query-export'` | Export endpoint path. |
| `fileName` | `string` | `export-<yyyy-mm-dd>` | Native: file name without extension. The server's `Content-Disposition` is not reachable through `client.post`, so the name is chosen on the device. |
| `share` | `boolean` | `true` | Native: open the share sheet after writing. |

### DocyrusDataExportPayload

| Field | Type | Description |
|-------|------|-------------|
| `dataSourceId` | `string` | Target data source id (required). |
| `columns` | `'*' \| ReadonlyArray<string>` | `'*'` (or omitted) for every exportable field, or field slugs with optional inline projections. |
| `filters` | `RuleGroupType \| null` | Filter group of the items query. |
| `filterKeyword` | `string` | Free-text keyword search. |
| `limit` | `number` | Maximum rows. Defaults to `defaultLimit`. |
| `format` | `'xlsx' \| 'csv'` | Export format (server-controlled, default `xlsx`). |
| `[key: string]` | `unknown` | Extra keys forwarded to the endpoint. |

### Result (`UseDocyrusDataExportResult`)

| Field | Type | Description |
|-------|------|-------------|
| `exportData` | `(payload: DocyrusDataExportPayload) => Promise<DocyrusDataExportFileResult \| null>` | Run the export and share the file. Resolves `null` when `expo-file-system` is missing. |
| `isExporting` | `boolean` | True while the request runs. |
| `error` | `Error \| null` | Last error (cleared on every new attempt). |

### DocyrusDataExportFileResult

| Field | Type | Description |
|-------|------|-------------|
| `uri` | `string` | Local `file://` URI in the cache directory. |
| `fileName` | `string` | File name including the extension. |
| `mimeType` | `string` | MIME type. |

## Differences from web

- Web calls `client.download()`, which saves through the browser. Native POSTs with `responseType: 'arrayBuffer'`, writes the bytes with `expo-file-system` and shares them with `expo-sharing`.
- `exportData` resolves the written file (`DocyrusDataExportFileResult`) instead of `void`.
- Native adds the `fileName` and `share` options.

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusDataExportOptions` | Hook options. |
| `UseDocyrusDataExportResult` | Hook result. |
| `DocyrusDataExportPayload` | Request payload. |
| `DocyrusDataExportFileResult` | Written file metadata. |