Exporting Data

This guide covers how to export variable data and dimension tables from Farseer.

Exporting Variable Data

export.exportFormula()

The primary method for retrieving variable data. Returns a Blob that can be parsed into an Arquero table.

import { ExportFormat } from 'farseer-client';
import * as aq from 'arquero';

const blob = await client.export.exportFormula({
    format: ExportFormat.Csv,
    formula: 'sum("Revenue", "Y2024", "Plan")'
});

const data = aq.fromCSV(await blob.text());
data.print();

Formula Syntax

The formula follows Farseer's expression language:

// Basic: sum(variable, dimension1, dimension2, ...)
formula: 'sum("Revenue", "Y2024", "John")'

// With version/scenario
formula: 'sum("Cost", "Y2024", "Actual")'

// Multiple dimension filters
formula: 'sum("Sales", "Y2024", "Q1", "North Region", "Product A")'

Calculate On-Demand Cells First

If your model has calculated fields, call calculateOnDemandCells() before exporting:

// With timeout wrapper (recommended)
const calc = client.cells.calculateOnDemandCells();
const timeout = new Promise(resolve =>
    setTimeout(() => resolve('timeout'), 10 * 60 * 1000)
);

const result = await Promise.race([calc, timeout]);
if (result === 'timeout') {
    console.log('Calculation timed out, continuing...');
}

// Now export
const blob = await client.export.exportFormula({...});

---

Exporting Variable as Arquero Table

data.loadFarseerVariable()

Directly exports a variable as an Arquero table with selected dimensions:

// Export with all dimensions
const { table, config } = await client.data.loadFarseerVariable('Revenue');
table.print();
// | Years  | Months | Versions | Products | Revenue |
// |--------|--------|----------|----------|---------|
// | 2024   | 1      | Plan     | Jabuka   | 10      |
// | 2024   | 1      | Plan     | Torta    | 45      |

// Export with specific dimensions only
const { table: filtered } = await client.data.loadFarseerVariable(
    'Revenue',
    'Versions',
    'Products'
);
filtered.print();
// | Versions | Products | Revenue |
// |----------|----------|---------|
// | Plan     | Jabuka   | 21      |
// | Plan     | Torta    | 95      |

---

Exporting Dimension Tables

data.loadFarseerDimensionTable()

Loads dimension table data as an Arquero table:

const { table, metadata } = await client.data.loadFarseerDimensionTable('Products');
table.print();
// | Name      | Description | Category      |
// |-----------|-------------|---------------|
// | Product A | Desc A      | [Electronics] |
// | Product B | Desc B      | [Furniture]   |

caution

Dimension table connections (foreign keys) are stored as arrays. Always access with [0]:

// Wrong
table.filter(d => d?.['Category'] === 'Electronics');

// Correct
table.filter(d => d?.['Category'][0] === 'Electronics');

Large Tables with Batched Loading

For very large dimension tables, use batched loading:

for await (const { table } of client.data.loadFarseerDimensionTableBatched('LargeTable', 1000)) {
    console.log(`Loaded batch with ${table.numRows()} rows`);
    // Process each batch
}

---

Exporting to Files

Save as CSV in Farseer

import * as aq from 'arquero';

const data = aq.table({ Name: ['A', 'B'], Value: [100, 200] });
const folder = await client.getItemByPath(['Reports']);

await client.data.saveToCsvFarseerFile(data, 'output.csv', folder.id);

Using Evaluator Export

For complex exports with custom configurations:

const blob = await client.evaluatorExport(exportConfiguration);
const buffer = Buffer.from(await blob.arrayBuffer());
// Write to file or process further

---

Combining Exports with Arquero

A common pattern is exporting data, transforming it, and saving:

import * as aq from 'arquero';
import { op } from 'arquero';
import { ExportFormat } from 'farseer-client';

// Export
const blob = await client.export.exportFormula({
    format: ExportFormat.Csv,
    formula: 'sum("Revenue", "Y2024")'
});

// Transform
const data = aq.fromCSV(await blob.text());
const summary = data
    .groupby('Product')
    .rollup({ total: d => op.sum(d.Revenue) })
    .orderby(aq.desc('total'));

// Save result
const folder = await client.getItemByPath(['Reports']);
await client.data.saveToCsvFarseerFile(summary, 'revenue-summary.csv', folder.id);