Exporting Data Overview

BCCL makes it straightforward to export data from any Business Central table to your local machine, a file share, or directly into a SQL Server database. This page covers the fundamentals of the GETDATA task, how to discover available tables, and the general workflow for exporting data.

The GETDATA Task

The core of all data export operations in BCCL is the getdata task. You invoke it with the -t parameter:

bccl -t getdata -s table=18 -f json -o customers.json

This single command connects to Business Central, reads all records from table 18 (Customer), formats the output as JSON, and writes it to customers.json. Every export operation follows this same basic pattern: specify a table, choose a format, and optionally direct the output to a file.

How It Works

When you run a GETDATA command, BCCL sends a request to the BCCL extension installed in your Business Central environment. The extension opens the specified table, applies any filters you have provided, iterates through the records, and returns the data in the requested format. The client then writes the result to the output file or prints it to the console.

Discovering Available Tables

Before you can export data, you need to know the table number. Every table in Business Central has a unique numeric identifier. If you are not sure which table contains the data you need, use the tables task to search:

bccl -t tables -s name=Customer*

This returns a JSON list of all tables whose names match the wildcard pattern:

{
  "Tables": [
    { "No": 18, "Name": "Customer" },
    { "No": 21, "Name": "Cust. Ledger Entry" },
    { "No": 379, "Name": "Customer Amount" }
  ]
}

You can use the wildcard character * to broaden your search. A few useful examples:

Search Pattern	Finds
name=Customer	Exact match only
name=Customer*	Tables starting with "Customer"
name=Ledger	Tables containing "Ledger"
name=*Entry	Tables ending with "Entry"

Once you have found the table number, you can use it in your GETDATA command.

Basic Export Example

Here is a complete example that exports all customers to a CSV file:

bccl -t getdata -w https://server/BC/WS/CRONUS/Codeunit/bccl -u myuser -p mypassword -s table=18 -f csv -o customers.csv

Let us break down each parameter:

Parameter	Value	Purpose
-t	getdata	The task to execute
-w	https://server/BC/...	The Business Central web service URL
-u	myuser	Your Business Central username
-p	mypassword	Your password or web access key
-s	table=18	Settings: export from table 18 (Customer)
-f	csv	Output format
-o	customers.csv	Output file path

If you have previously used --remember to store your connection settings, you can shorten this to:

bccl -t getdata -s table=18 -f csv -o customers.csv

Core Parameters

Table Number (-s table=N)

The -s parameter passes settings to Business Central. The table setting is required for every GETDATA operation. It specifies the Business Central table number:

-s table=18

You can pass multiple settings by repeating the -s parameter or including them as separate arguments:

-s table=18 "view=where(No.=filter(10000..20000))"

Output Format (-f)

The -f parameter specifies the output format. BCCL supports five formats:

Format	Flag	Best For
JSON	-f json	API integration, web applications
XML	-f xml	Legacy systems, XSLT transformations
CSV	-f csv	Spreadsheets, database imports
Excel	-f xlsx	Direct spreadsheet use
SQL	-f sql	Direct SQL Server table population

If you omit -f, BCCL attempts to detect the format from the output file extension. For example, -o data.xml automatically selects XML format.

Output File (-o)

The -o parameter specifies where to write the exported data:

-o customers.csv
-o "C:\Data\Exports\customers.json"
-o /home/user/exports/customers.xml

If you omit -o, BCCL prints the output directly to the console (stdout). This is useful for piping output to other tools:

bccl -t getdata -s table=18 -f json | jq '.Customer[0]'

For the SQL format, -o specifies the target SQL table name rather than a file path, and it is mandatory. If you omit -o while using -f sql, BCCL does not write anything to the database; it simply prints the retrieved data to the console as JSON and exits without an error message. "No error, but no rows in SQL, just JSON in the console" is the normal symptom of a missing -o. The mapping file (-m) does not determine the target table name:

rem Writes to SQL
BCCL -t getdata -s table=<TableNo> -o "<SqlTableName>" -f sql -m "<path>\<Name>.mapping.json"

rem Only prints JSON to the screen (no SQL write)
BCCL -t getdata -s table=<TableNo> -f sql -m "<path>\<Name>.mapping.json"

Binary Fields (-b)

By default, BCCL skips binary fields (Blob, Media, and MediaSet types) during export. To include them, add -b true:

bccl -t getdata -s table=18 -f json -o customers.json -b true

Binary field values are exported as Base64-encoded strings. This significantly increases the output size, so only enable it when you specifically need binary data such as images or documents.

Paging for Large Datasets

When you export a table with many records, BCCL automatically splits the data into pages. The default page size is 1000 records. Each page requires a separate round-trip to Business Central.

You can adjust the page size with the -z parameter:

bccl -t getdata -s table=18 -f csv -o customers.csv -z 5000

Larger page sizes mean fewer round-trips but more memory usage on the Business Central server. Smaller page sizes are gentler on the server but take more time overall.

Page Size	Trade-off
100-500	Low server memory, many round-trips
1000 (default)	Balanced for most scenarios
5000-10000	Fewer round-trips, higher server memory

BCCL handles paging transparently. Your output file contains all records regardless of how many pages were needed. For CSV files, the header row appears only once at the top.

FlowFields

Business Central FlowFields are calculated fields that derive their values from other tables (such as the Balance field on the Customer table). BCCL automatically calculates FlowFields when they are included in your export. You do not need to do anything special; if a FlowField appears in your mapping file, BCCL calls CalcField for each record before reading the value.

Keep in mind that exporting tables with many FlowFields can be slower because each FlowField calculation requires additional database queries. Slow FlowFields are the main known cause of long export times and of intermittent export errors: if an export takes a long time or sometimes fails, suspect FlowFields first, lower the page size (-z), and drop FlowFields you do not need from the mapping. See Export Performance and Intermittent Export Errors.

Console Output

When you omit the -o parameter, BCCL writes directly to stdout. This is helpful for:

• Quick data inspection without creating files
• Piping data to other command-line tools
• Scripting and automation where you process the output inline

For example, to quickly check a customer record:

bccl -t getdata -s table=18 "view=where(No.=filter(10000))" -f json

This prints the JSON directly to your terminal.

Typical Export Workflow

A complete data export workflow typically follows these steps:

1. Find the table: Use -t tables -s name=... to locate the table number.
2. Generate a mapping file (optional): Use -t mapping -s table=N -o mapping.json to create a mapping template. Edit it to select and rename the fields you need.
3. Export the data: Run -t getdata with your table number, format, and optional mapping file.
4. Refine with filters: Add view filters to narrow the data to exactly what you need.

Here is that workflow in practice:

rem Step 1: Find the table
bccl -t tables -s name=Item*

rem Step 2: Generate mapping
bccl -t mapping -s table=27 -o items.mapping.json

rem Step 3: Edit mapping file to keep only desired fields
rem (Use any text editor)

rem Step 4: Export with mapping and filter
bccl -t getdata -s table=27 "view=where(Type=filter(Inventory))" -f csv -o items.csv -m items.mapping.json

All Responses Are JSON

When BCCL executes a task that does not return tabular data (such as the tables task), the response is always JSON, regardless of the -f parameter. Tabular export tasks like getdata respect the format you specify.

SQL Server Direct Export

For the SQL format, BCCL writes data directly to a SQL Server table rather than to a file. This requires the --sqlconnect parameter with a connection string and -o to specify the target table name:

bccl -t getdata -s table=18 -f sql -o Customer --sqlconnect "Server=myserver;Database=BCDATA;Trusted_Connection=True"

SQL export is covered in detail in the Output Formats section.

GETDATA Always Transfers Everything

GETDATA performs a full data transfer on every run. It reads all records matching the view filter and writes them all to the destination; it has no built-in memory of what was transferred last time.

With -f sql, records that already exist in the target SQL table are matched on primary key and updated rather than inserted. A second run of the same command therefore produces console output like:

Sql table [Post Code], 0 inserted, 1000 updated
Sql table [Post Code], 0 inserted, 1000 updated

(one line per page of -z records). This is expected behaviour, not an error.

To avoid re-writing unchanged rows on every run, add a view filter on the SystemModifiedAt system field so that only recently changed records are transferred. See "Filtering on System Fields (Incremental Exports)" in Filtering Data and Scheduling Replication.

Expected Output and Troubleshooting

A getdata command such as bccl -t getdata -s table=21 returns the table data in the requested format (JSON on the console when -f and -o are omitted). If the output looks wrong:

Symptom	Meaning	See
The single line BCCL.BigStringBuilder instead of data	The result was not rendered. This is a tooling/version issue with the client, not an error about the table or your data. Install the latest client and re-run the same command.	Client Versions and Updates
{"<Table Name>":[]}	The table returned no records for the filter. Not an error.	SQL Output Issues
JSON on the console although -f sql was given	-o is missing, so nothing was written to SQL.	SQL Output Issues
Version mismatch (... vs. ...)	The client is older than the BC extension requires. Update BCCL.EXE.	Client Versions and Updates
Sorry, the current permissions prevented the action. (TableData ...)	A previously working export can start failing after the environment changes (for example an extension such as LS Central is installed or updated), because the user or Entra application used by BCCL lacks permission on a table introduced or touched by that extension. Assign the extension's permission set (for example LSCentralPermissions) or, as a last resort, SUPER (Data) to the Microsoft Entra application in BC.	Permission Errors
Field ... is obsoleted	The mapping refers to a field Microsoft has obsoleted. Remove it from the mapping.	Mapping Files
Unauthorized The credentials provided are incorrect after many pages	The token expired mid-transfer. Put the authentication parameters on the getdata command line.	Running Long or Unattended Transfers Reliably

Tips and Best Practices

• Start with a small export (use a filter) before exporting entire tables to verify your setup.
• Use mapping files to limit the exported fields. Exporting only what you need is faster and produces smaller files.
• For recurring interactive exports, use --remember to save your connection parameters so you do not have to type them every time. For long-running, scheduled, or multi-company runs, put all parameters on the command line instead (see Running Long or Unattended Transfers Reliably).
• Increase the page size (-z) for large tables to reduce the number of round-trips to Business Central; decrease it if exports with FlowFields are slow or fail intermittently.
• Use verbose mode (-v) to see detailed information about what BCCL is doing, which is helpful for troubleshooting.

Related Topics

• Filtering Data
• Mapping Files
• Output Formats
• CSV Formatting
• Export Performance and Intermittent Export Errors
• Command Reference