Skip to main content

File Operations

The Farseer Client provides methods for navigating folders, uploading, downloading, and working with files.

getItemByPath()​

Navigate to any file or folder using a path array:

const file = await client.getItemByPath(['Finance', 'Reports', 'data.xlsx']);
console.log(file.id);        // 123
console.log(file.reference);  // UUID for file download

getFolderItems()​

List all items in a folder:

// By folder name
const items = await client.getFolderItems('Reports');

// By folder ID
const items = await client.getFolderItems(folderId);

getFolderItem()​

Get a specific item from a folder:

const file = await client.getFolderItem('Files', 'data.xlsx');

findItemNode()​

Search for an item by name and type:

const folder = await client.findItemNode('Reports', 'FOLDER');

Downloading Files​

Download a File as Blob​

const fileItem = await client.getItemByPath(['Finance', 'data.xlsx']);
const blob = await client.farseerFiles.get(fileItem.reference);

// Convert to Buffer
const buffer = Buffer.from(await blob.arrayBuffer());

Load Excel as Arquero Table​

const fileItem = await client.getItemByPath(['Finance', 'data.xlsx']);
const table = await client.data.loadXlsxFile(fileItem);
table.print();

Load Excel Worksheets​

const worksheets = await client.readExcelWorksheetsFromFarseerFile('Finance', 'data.xlsx');
// Returns parsed worksheet data for each sheet

Get ExcelJS Workbook​

const workbook = await client.createExcelWorkbookFromFarseerFile('Finance', 'data.xlsx');
// Full ExcelJS workbook object for advanced operations

Uploading Files​

Upload a File​

const folder = await client.getItemByPath(['Finance', 'Reports']);

await client.farseerFiles.create(
    blob,       // File data as Blob
    'GENERAL',  // Category
    folder.id
);

Create or Update File​

await client.createOrUpdateFarseerFile(
    { fileName: 'report.csv', folderId: folder.id },
    buffer  // Buffer or Blob
);

Save Arquero Table as CSV​

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);

Deleting Files​

const file = await client.getItemByPath(['Finance', 'Temp', 'old.csv']);
await client.folders.deleteItemsBatch([{ id: file.id }]);

Listing Folder Contents​

// List root folder items
const rootItems = await client.folders.listItemsBatch([{ id: null }]);
const filesFolder = rootItems[0].items?.find(f => f.name === 'Files');

// List items in a specific folder
const items = await client.folders.listItemsBatch([{ id: folderId }]);

Complete Example: Process Excel and Import​

async function processExcelFile(client: FarseerClient) {
    // 1. Load Excel file
    const fileItem = await client.getItemByPath(['Data', 'input.xlsx']);
    const table = await client.data.loadXlsxFile(fileItem);

    // 2. Transform data
    const processed = table.derive({
        Adjusted: d => d?.['Value'] * 1.1
    });

    // 3. Save processed data back
    const folder = await client.getItemByPath(['Data', 'Output']);
    await client.data.saveToCsvFarseerFile(processed, 'processed.csv', folder.id);

    // 4. Import into Farseer variables
    const importJob = await client.createImportJob({
        title: 'Excel import',
        columns: [
            { type: 'DIMENSION_TABLE', dimensionTableName: 'Products' },
            { type: 'VARIABLE', variableName: 'Revenue' },
        ],
        labels: ['auto', 'excel-import']
    });

    const rows = processed.objects().map((r: any) => [r['Product'], r['Adjusted']]);
    await importJob.addRows(rows);
    await importJob.flushRows();
    await importJob.undoPrevious();
    await importJob.commit();
}