useDocyrusDataExport

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.

Edit on GitHubEditllms.txt

iOSAndroidExpo Go

Installation

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

Required Packages(4 packages)

pnpm add @docyrus/api-client @react-querybuilder/core expo-file-system (optional) expo-sharing (optional)

The hook needs an authenticated RestApiClient. Unlike useDataExport, 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 DocyrusDataExportMenu 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

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 (
    <Button
      loading={isExporting}
      onPress={() => void exportData({
        dataSourceId,
        columns: ['name', 'status(id,name)', 'due_date'],
        filters: query,
        filterKeyword: keyword
      }).catch(() => undefined)}>
      Export
    </Button>
  );
}

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.

useDocyrusDataExport

On this page