Examples

Complete, runnable examples demonstrating common farseer-client use cases.

Load Dimension Table

Load a dimension table and print it as an Arquero table.

import * as farseer from 'farseer-client';

async function main() {
    const client = new farseer.FarseerClient();
    const { table, metadata } = await client.data.loadFarseerDimensionTable('Products');
    table.print();
}

main().catch(farseer.handleUnknownError);

---

Export Variable Data

Export a variable with all dimensions or specific dimensions.

import * as farseer from 'farseer-client';

async function main() {
    const client = new farseer.FarseerClient();

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

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

main().catch(farseer.handleUnknownError);

---

Import from Excel File

Load an Excel file from Farseer and import its data.

import * as farseer from 'farseer-client';

async function main() {
    const client = new farseer.FarseerClient();

    // Load Excel file
    const fileItem = await client.getFolderItem('Files', 'data.xlsx');
    const dataTable = await client.data.loadXlsxFile(fileItem);

    // Import data
    const importJob = await client.data.importDataTable({
        data: dataTable,
        title: 'Import from Excel',
        columns: [
            { type: 'DIMENSION_TABLE', dimensionTableName: 'Product' },
            { type: 'DIMENSION_TABLE', dimensionTableName: 'Cost Center' },
            { type: 'VARIABLE', variableName: 'Revenue' },
        ],
    });
    await importJob.commit();
}

main().catch(farseer.handleUnknownError);

---

SQL Server to Farseer Sync

Query SQL Server and sync dimension tables to Farseer.

import * as farseer from 'farseer-client';
import * as mssql from 'mssql';

async function main() {
    const client = new farseer.FarseerClient();
    const pool = await mssql.connect({
        user: 'your_username',
        password: 'your_password',
        server: 'your_server',
        database: 'your_database',
    });

    const data = await client.data.mssqlQuery(pool, `
        SELECT * FROM [dbo].[MonthSharesExtended]
        WHERE [Y] = 2023 AND [M] = 1
    `);

    const brickData = data.select('RegionId', 'AreaId');
    const sourceTypeData = data.select('ProductId', 'OTC3', 'EPH3');

    await client.data.syncMultipleTables([
        {
            name: 'Brick',
            columns: [
                { name: 'regionId', type: farseer.ModelTableColumnType.PrimaryKey },
                { name: 'areaId', type: farseer.ModelTableColumnType.ForeignKey, foreignKeyTableName: 'Area' },
            ],
            rows: brickData,
        },
        {
            name: 'Source Type',
            columns: [
                { name: 'productId', type: farseer.ModelTableColumnType.PrimaryKey },
                { name: 'otc3', type: farseer.ModelTableColumnType.ForeignKey, foreignKeyTableName: 'OTC3' },
                { name: 'eph3', type: farseer.ModelTableColumnType.ForeignKey, foreignKeyTableName: 'EPH3' },
            ],
            rows: sourceTypeData,
        },
    ]);

    await pool.close();
}

main().catch(farseer.handleUnknownError);

---

External REST API Integration

Fetch data from an external API with pagination and convert to Arquero table.

import * as farseer from 'farseer-client';

async function main() {
    const api = await farseer.RESTApi.createInstance(
        'https://api.example.com',
        {
            headerKey: 'Authorization',
            headerValue: 'Bearer my-token',
        }
    );

    const dataTable = await api.requestAndConvert({
        mainRequest: { method: 'GET', url: '/api/cities/42' },
        paginationSettings: {
            paramHandlingType: 'query',
            limitParamName: 'limit',
            limitParamValue: 100,
            offsetParamName: 'offset',
        },
        responseTransform: (response: any) => response?.body?.data?.cities,
    });

    dataTable.print();
}

main().catch(farseer.handleUnknownError);

---

Export Formula to Arquero

Export variable data using formula expressions and work with Arquero.

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

async function main() {
    const client = new farseer.FarseerClient();

    // Calculate on-demand cells first
    await client.cells.calculateOnDemandCells();

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

    // Parse and work with Arquero
    const data = aq.fromCSV(await blob.text());
    data.print();

    // Transform
    const summary = data
        .groupby('Product')
        .rollup({ total: (d: any) => op.sum(d.Revenue) });

    summary.print();
}

main().catch(farseer.handleUnknownError);

---

Save Arquero Table to Farseer

Create a table in Arquero and save it as a CSV in Farseer's file system.

import * as farseer from 'farseer-client';
import * as aq from 'arquero';

async function main() {
    const client = new farseer.FarseerClient();

    // Create or load an Arquero table
    const data = aq.table({
        Product: ['Widget A', 'Widget B', 'Widget C'],
        Revenue: [50000, 75000, 30000],
        Quarter: ['Q1', 'Q1', 'Q1']
    });

    // Get destination folder
    const folder = await client.getItemByPath(['Reports', 'Quarterly']);

    // Save as CSV
    await client.data.saveToCsvFarseerFile(data, 'q1-revenue.csv', folder.id);
}

main().catch(farseer.handleUnknownError);

---

Evaluate Revenue by Month

Use the evaluator to compute Revenue per month without a full export.

import * as farseer from 'farseer-client';

async function main() {
    const client = new farseer.FarseerClient();

    const revenue = await client.getVariable('Revenue');
    const plan = await client.getDimensionMember('Versions', 'Plan');
    const y2024 = await client.getDimensionMember('Years', 'Y2024');
    const months = await client.getDimensionMembersForTable('Months');

    const monthQueries: farseer.CellQuery[] = months.map(m => ({
        type: 'VARIABLE',
        formula: `sum(RV,P,Y,$${m.id})`,
    }));

    const cells = await client.evaluator.evaluate({
        filters: [
            ['RV', `$${revenue.id}`],
            ['P', `$${plan.id}`],
            ['Y', `$${y2024.id}`],
        ],
        cellQueries: [
            { type: 'VARIABLE', formula: 'sum(RV,P,Y)' },
            ...monthQueries,
        ],
    });

    console.log(`Total: ${cells[0].value}`);
    cells.slice(1).forEach((cell, i) => {
        console.log(`  ${months[i].name}: ${cell.value}`);
    });
}

main().catch(farseer.handleUnknownError);