The Exporter builds a CSV, YAML or JSON file from a schema’s objects. It is reached from the sidebar (Tools > Exporter), or from a schema’s object list through Action > Export, which prefills it with that list’s current view and search query.

Requires the p_data_export permission, plus read permission on the schema being exported.

Source

Schema - the schema to export. The selector only lists schemas you may read.

Search query - the same syntax as the list page search box. Leave it blank to export every object. There is no * wildcard here: a blank query is “everything”. Only objects you are allowed to read are written to the file.

Columns

The panel on the right of the form lists every column the schema can export, one checkbox each, showing the field name and its displayname. The boxes you tick, in the order they are listed, are the columns of the file. There is no way to reorder them.

_schema and keyname are always ticked and cannot be unticked. _schema is what makes the file re-importable; keyname is what identifies the row.

Select all / Select none toggles every other box at once; the button label follows the current state.

What is offered, in order:

Group	Columns
Builtin attributes	displayname, is_enabled, last_sync, last_update
Schema fields	every declared field, in schema order
injected	subfields resolved through a schema reference or an external field, named <field>__<subfield> (for example myuser__email)

Injected columns start unticked. They are computed at read time: useful in a report, but not written back if the file is re-imported. Their names are derived from the schema and from one sample object, so treat the list as a hint - an object without the reference set exports an empty cell rather than failing.

Enumerate subfields are not listed. They come from the value each object selected, so the list differs from object to object. In YAML and JSON they are exported automatically, right after their parent, whenever the enumerate column itself is ticked; they are never exported to CSV, where one fixed header cannot depend on each row’s value.

Arriving through Action > Export from an object list pre-ticks the columns of the view that list was showing, instead of the default set. A view column the panel cannot offer is left unticked. Nothing here changes which view your list page shows next.

An export is a snapshot of the schema as it is now: a field added later is not picked up by a bookmarked URL or a repeated export - re-open the Exporter and tick the new box.

Format

CSV, YAML or JSON. The CSV delimiter and encoding selectors only apply to CSV.

Text fields (dataformat: text) are never written to CSV - they routinely contain newlines and delimiters. They are exported normally in YAML and JSON.

The schema column

Always present, and not an option: it is what makes an export re-importable. cavaliba load and the Import Tool need either this column, a pipeline, or a forced schema to know what each row is.

It is the leading _schema column in CSV, and the classname key in YAML/JSON - the YAML/JSON file carries classname only, never a second _schema key.

The CSV column is named _schema, with the underscore, on import as well as on export - that is the only spelling the importer recognises (neither schema nor classname is). The underscore marks it as a directive rather than a real field, like _action.

Options

Add an _action field - adds an _action column (CSV) or key (YAML/JSON) with the same value on every row, so the file is ready to be edited and re-imported. noop is the safe choice: re-importing it unchanged does nothing.

In CSV the column is optional and, when present, comes first - ahead of _schema - so the cell you edit before re-importing is the leftmost one in a spreadsheet.

Inline refs (YAML/JSON) - a comma-separated list of schema names, or * for all. Each referenced object is inlined under a _refs key. Only reference fields actually selected for export contribute.

Revisions (YAML/JSON) - include the last N revisions of each object under a _revision key.

Synchronous and background exports

An export matching no more than EXPORT_INTERACTIVE_MAX_SIZE objects (default 5000, see Configuration > data) is built during the request and downloads immediately.

Above that threshold it runs as a background task, and a progress window opens showing percent complete, total, done, success and error counts, elapsed and remaining time, the rate in objects per second, and the first few errors. When the task finishes, a download link appears in the same window.

While the export is running, the buttons depend on p_task_view:

	With p_task_view	Without
Abort - stops the task; the partial file is deleted, never offered for download	yes	yes
Hide - closes the window, leaves the task running	yes	no

Hiding is only offered to someone who can follow the task afterwards from the Tasks menu. Without that permission this window is your only view of the export, so it cannot be dismissed while the export runs - clicking outside it and pressing Escape do nothing either. Abort is always available, so you are never stuck with a run you no longer want.

Once the export is finished (or aborted, or failed), the window shows Close instead, for everyone: there is nothing left to follow, and the download link is right there.

A background export aborts by itself if more than CAVALIBA_MAX_EXPORT_ERROR objects (default 20) fail.

Note that Total counts the objects matched by the query, while Success counts the ones actually written: objects you are not allowed to read are scanned but skipped.

Result files

A background export’s file is kept for CAVALIBA_EXPORT_FILE_TTL_HOURS (default 24, so one day) and then removed by the nightly housekeeping.

There are three ways to get to it:

1. the download link in the progress window, as soon as the export finishes;
2. the Tasks menu in the top bar - a finished export shows a download icon directly in the task list;
3. the task’s own detail page, under Result.

Routes 2 and 3 are what you use after hiding the window or leaving the page. They need p_task_view (to see the Tasks menu at all) on top of p_data_export. Only the task’s owner can download the file - or anyone with p_task_all.

If you have no task permission, the progress window is your only route, so keep it open until the link appears. The handle is in the URL, so the direct link /data/private/exporter/result/<handle>/ also works if you kept it.

Download page

Tools > Download lists the files produced by the exporter.sh cron script in the export folder (CAVALIBA_EXPORT_FOLDER), for preview or download. This is a different area from the result files above, and requires p_data_export_viewer.

After an upgrade

The sidebar and dashboard are driven by the SIDEBAR_CONTENT / DASHBOARD_CONTENT configuration entries, which are only seeded from their defaults when no stored value exists yet. So on an install that already has them:

• The existing Export entry needs no change - it keeps its app: export key and now opens the Exporter.
• The new Download entry is not added automatically. Add - app: download to the Tools section of SIDEBAR_CONTENT (and of DASHBOARD_CONTENT if you want the tile) under Configuration > home. Until then the page is only reachable at /data/private/download/.

Spreadsheet formulas

Cell values are written exactly as stored. A value starting with =, +, - or @ is treated as a formula by Excel and LibreOffice when the CSV is opened directly.

Cavaliba deliberately does not escape them: escaping changes the value, and the whole point of the _schema / _action columns is that the file can be re-imported unchanged. For an export whose content you do not control, open it through the spreadsheet’s import dialog (as text) rather than by double-clicking it.

Notes

• In a development setup with CAVALIBA_TASK_CELERY=sync, there is no worker: a background export runs inside the request instead, so the progress window opens on an export that has already finished.
• A background export needs the worker to share the same CAVALIBA_FILESTORE volume as the web nodes, exactly like the Import Tool.
• The column panel enumerates its selection, so the UI always asks for an explicit column list. The API and CLI (cavaliba get) instead accept the filter grammar the UI no longer shows - * for every column, !a,b for every column except those, or an explicit comma-separated list. In that filter mode, CSV never emits injected subfields: the header is resolved from the first exported object, and an object without the reference set would write one cell less and shift every following column. Naming an injected column explicitly works in every mode.