Documents and spreadsheets

Turn PDFs, Word files, spreadsheets and other documents into dataset rows, one record per document.

A file processor can read documents for you. You upload them to a File Set, describe the fields you want, and Beetl reads each document and returns one record per document. Valid records are published to a dataset automatically, and anything Beetl is unsure about waits for you to check it. Use it for invoices, contracts, delivery notes, forms and any other files where the data sits in a layout meant for people.

Any user can create and configure these processors.

What you can upload

A Documents processor accepts PDFs, Word, Excel and PowerPoint files, HTML, images, plain .json and many other formats. Audio and video are not supported. Each document can be up to 20 MiB, and a PDF can have up to 30 pages. A document that is too large or too long fails, and its record shows the reason.

For Excel workbooks with a fixed layout, a Spreadsheet processor is an alternative that uses no AI.

Set up a Documents processor

Upload your documents. On Home, drop them onto the canvas or into the File sets dialog, or right-click the canvas and choose New file processor and add them there. Beetl creates a file processor, which shows on Home as a File processor card reading Needs configuration.

Open the processor. Select the node and choose Open processor in the panel on the right, or double-click it. A processor that is not set up yet opens on its Settings tab.

On Settings, name the processor and choose the file group it reads, or upload a new one. Then pick an example document. A preview of the source appears beside the settings.

Choose Suggest fields. Beetl analyzes the example and proposes fields. A confirmation asks "Analyze this source with AI? Charges may apply." before it starts. You can also add fields by hand, edit the proposed ones, and write instructions that apply to every document.

Choose the AI model, then choose Preview output to see the record Beetl would produce for your example. Adjust the fields until it looks right. Recover analysis is there if an analysis you started did not come back.

Choose Start processing. Beetl reads every file in the set and creates the dataset.

Open the Files tab to follow progress and review the results.

The page updates on its own about every 10 seconds while documents are processing. The processor's Dataset link jumps to the dataset on Home.

Define the fields

You can define up to 100 fields. Each field has a name and a kind.

Kind	Use it for
Text	Names, descriptions, references and other free text
Number	Plain numbers such as quantities
Currency	Amounts of money
Metric	Measured values such as weights or volumes
Date and time	Dates and timestamps
Address	Postal addresses
Choice	A value that must be one of a list you define
Object	A group of related fields, such as a supplier with a name and a tax number
Table	A repeating set of rows, such as the line items on an invoice

Fields are typed, so a number is a number in the dataset and a date is a date. A field can be required. A record that fails validation or lacks a required field is not published as it stands. It waits for review.

Processing and results

Processing reads every file in the set. The Files tab lists the documents with a status, has a search box, and lets you upload more files or choose Process files to process them.

Status	Meaning
Waiting	The document has not been processed yet.
Processed	The record is valid and published to the dataset.
Needs review	The record failed validation or lacks a required field.
Failed	The document could not be read, for example because it is too large or too long. The record shows the reason.

The dataset gets one row per document. Extra columns identify the source file. A banner on the page reads Dataset update pending while new records are being published, and Dataset update failed with a reason if publishing did not work.

Review and correct records

Open a record that needs review. You see the source document beside an editor for its fields. For each value, the editor shows the evidence Beetl found in the document and any alternative readings, so you can pick the right one or type your own.

Choose Save correction to save your edits. Beetl validates the record again and, if it is valid, publishes it to the dataset.
Choose Re-analyze to run the AI on that document again. A confirmation mentions that charges may apply.

There is no approve or reject step. Until a record's issues are resolved, the dataset keeps the last values that were accepted for it. If you save a record that someone else has just changed, you get a conflict message. Reload the record and apply your edit again.

Cost and AI

Suggest fields, processing each document and Re-analyze use AI. They use your tenant's monthly AI credits when it runs on managed AI, or your own AI key if you have registered one. See AI in a tenant. CSV, NDJSON and Parquet imports and spreadsheet mapping use no AI.

Document text is sent to the AI provider your tenant is configured to use, as it is for chat. If AI is not available for your tenant, Suggest fields and document processing cannot run: they need AI to be available for your tenant.

Change the fields later

Once the dataset exists, its schema is locked, so the fields of a running processor cannot be changed. To use different fields, choose Create a new dataset. Beetl writes the new fields to a new dataset and keeps the old one with its data. Pipelines that read the old dataset keep working.

Deleting a processor also keeps its dataset.

Spreadsheets

A Spreadsheet processor reads .xlsx workbooks without AI. Instead of describing fields for an AI to find, you map them yourself in the mapping editor:

By row ranges, so that you map a range of rows to columns.
By selected cells, so that you map individual cells to columns.

The processing steps are the same: choose Start processing, then follow results on the Files tab. A Spreadsheet processor accepts only .xlsx files, so dropping another format on it is refused. Dropping a file with the name of an existing one asks you to confirm the replacement. Rows mapped by range also identify their sheet and row in the dataset.

Using the assistant

The assistant can open the processor screens for you and propose edits to a processor, such as fields and instructions. Actions that save, analyze, process or re-analyze need your confirmation in the chat, and actions that only read do not. See Build with the assistant.

The assistant and MCP clients can also read processors, their documents, the extracted records and the source text. These tools only read. See the MCP tool reference.