Buckets

What are Buckets?

A Bucket is a structured table that lives inside Tavnit. Flows, Signals, Nets, agents and pipelines write rows into it automatically, you can add rows over the API or from a CSV or Excel file, and you can filter, sort, chart and question the result without exporting it anywhere.

A flow run stores the result of one document. A Bucket is where results accumulate across every run, so the question changes from “what did this invoice say?” to “what have we been billed this quarter?”. Every row has to match the Bucket's columns, which is what keeps that aggregate meaningful.

A Tavnit Bucket named Data Set open in the grid view. Typed columns for age, sex, bmi, children, smoker, region and charges hold 1,339 rows, with Insert, Filter, Sort, function row, Graph and Export controls in the toolbar and a column list plus connected flows in the left panel. — A Bucket in the grid. Column types are shown beside each name, and the row count and paging sit along the bottom.

Flows + Buckets

Turn on Bucket Export on a flow and map its output fields to Bucket columns. From then on, every successful run appends its rows, so results from many documents build up in one table.

When to Use Buckets

Buckets are ideal for:

Aggregating extraction results from many flow runs into a single table
Keeping reference data (price lists, catalogues, customer lists) that Cleaners look values up against
Syncing data in and out of external systems over the API
Collecting the structured output of Signals, Nets and agents next to your document data
Answering questions about your data in plain language, without a spreadsheet

Buckets vs Flow Runs

Flow runs store individual document results. Buckets aggregate data across runs and other sources into one table you can query, chart and export.

Creating a Bucket

Owners and Admins can create Buckets:

1Go to Buckets in the sidebar and click "Create Bucket" (or start "From template")
2Enter a name and, optionally, a description, then pick an icon and a color
3Click "Create Bucket". Tavnit then offers "Manage Access" to set who can see it, or "Open Bucket" to go straight to the grid
4Add columns: in the grid use "Insert" → "Insert Column", or import a CSV or Excel file and let Tavnit create the columns for you
5To fill it from a flow, open the flow, turn on "Bucket Export", link this Bucket and map the flow's fields to its columns

Each column has a name and a data type: Text, Number, Date, Checkbox or Dropdown (a fixed list of at least two options). Types are what let sorting, filtering, aggregation and charts behave correctly, so a numeric column that arrives as text is worth fixing at the source.

Column names matter

When writing over the API, every row must use the Bucket's column names. A row with a column the Bucket doesn't have aborts the whole write with a column mismatch error, so choose clear, consistent names upfront.

Finding Your Bucket ID & Name

To use the Buckets API, you need your bucket's ID and name. Both are on the bucket's details page:

1Go to Buckets and click "View details" on the Bucket you want
2Copy the Bucket name from the header (it has a copy button)
3Open "Bucket ID" under "Features" and copy the ID

The details page also has a Schema tab (every column, its type and flags), a Write History tab (each write, its source and how many rows it added), and Linked Flows, the flows that export into this Bucket.

Safety check

The API requires both bucket_id and bucket_name to prevent accidental reads and writes on the wrong bucket. If the name doesn't match the ID, the request is rejected.

Where the data comes from

Nothing about a Bucket assumes the data came from a document. Every source below writes into the same table, which is what makes a Bucket useful as reference data as well as a destination.

Source	How it works	Typical use
Bucket Export on a flow	Each successful run appends its rows, with extracted fields mapped onto Bucket columns.	Accumulating every invoice you process into one table.
A Cleaner action	An action edits a value in an existing Bucket row that a Lookup matched.	Marking an order received, or decrementing a stock count.
An agent	An agent with a Bucket delivery writes its captures into the Bucket after each run.	Recording live supplier prices fetched from a portal.
Signals and Nets	A Signal can export the rows it structures from each recording; a Net can export the rows of each completed catch.	Tracking call outcomes or social posts alongside document data.
A pipeline	A Bucket node on the canvas stores what the steps before it produce.	Ending a multi-step pipeline in a table.
The REST API	Append rows, or replace the table's rows, with one request.	Syncing a price list or customer catalogue from another system.
CSV or Excel import	Upload a .csv, .xlsx or .xls file from the grid.	Loading an existing spreadsheet once.
The grid itself	Anyone with edit access can add rows and type, paste or clear values.	Quick corrections and manual entries.

Buckets read as well as write

A Bucket is not only a destination. Cleaner Lookup fields pull values out of one to enrich a row, and Bucket Check fields ask whether a row already exists, which is how de-duplication works. Load your catalogue into a Bucket and every flow can match against it.

Exports are always un-pivoted

If a Cleaner reshapes rows into wide format for delivery, the Bucket still receives the original long-format rows. Stored data keeps one row per record so aggregates and lookups stay correct.

Working with the data

The grid is closer to a spreadsheet than a read-only report. You can edit in place, copy and paste cells, filter and sort, and page through large tables, so a Bucket with thousands of rows stays usable in the browser.

Control	What it does
Insert	Add a row or a column, import a CSV or Excel file, or open Prompting.
Filter	Narrow the view to rows matching conditions you set on any column.
Sort	Order the rows by a column, ascending or descending.
`f(x)`	Show a function row under the grid with the sum, average, minimum, maximum or count of each column, calculated on the current page.
Graph	Build a chart from the data (see Charts below).
Chat	Open a side panel to ask questions about the data (see below).
Export	Download every row in the Bucket as a CSV file.
Undo / redo	Step back and forward through edits made in the grid.

People with view-only access see the same grid with a read-only notice: they can filter, sort, chart and export, but not edit.

AI Search on a column

Exact matching fails when the same thing is written different ways: “Acme Corp.”, “ACME Corporation”, “acme”. AI Search lets a Cleaner match on meaning instead.

1Open the Bucket, click a text column's header and choose "Edit column"
2Turn on "AI Search"
3Set the minimum similarity (1 to 100%, default 90%). Below that threshold a lookup returns empty instead of a weak match
4Click "Save Changes". Tavnit indexes the column's values in the background

Once it is on, a Cleaner Lookup can use the AI Match operator against that column to find the closest row even when the text doesn't match exactly. AI Search is available on text columns only.

Prompting: ask questions in plain language

Prompting answers questions like “What is the total amount invoiced by each supplier this year?” straight from the Bucket, and shows how it got there.

1In the grid, open "Insert" → "Prompting"
2Under "Set up Prompting", choose the text columns to index and click "Enable". Tavnit groups their distinct values into categories so questions can filter by meaning
3Type your question under "Ask a Question" (up to 2,000 characters) and click "Ask"

Each answer comes with the Assumptions it made, the Matched values it included or excluded, the result with a Breakdown where relevant, and Sample rows so you can check the data behind it. Past questions stay in History.

Access

Setting up Prompting requires edit access to the Bucket.

Chat with the data

The Chat button in the grid opens a side panel where you can have a conversation about the Bucket: totals, breakdowns, or “show me” requests. When an answer refers to a set of rows, click Show in grid to filter the grid to them, and Clear view to go back. Chats are saved, so you can return to one later or start a New chat.

Chat needs Prompting enabled on at least one text column of the Bucket
Each organisation has a daily message allowance, shown in the panel; it resets the next day
Messages are limited to 2,000 characters

Enabled on request

Bucket chat is enabled per organisation. If you don't see the Chat button, contact support to turn it on.

Access Control

Every bucket has a visibility setting and supports per-member access grants, so you can control exactly who can see or edit your data. Owners and Admins manage it from Access on the details page.

Org-visible (default)

All members of your organisation can view the bucket. By default Admins can edit and Members can only view; you can change that person by person.

Private

Only the Owner and users who have been explicitly granted access can see this bucket. Only the organisation Owner can make a bucket private, and Admins and Members without a grant lose access immediately.

Each person can be given one of two access levels:

View only: can open the bucket and read its data
Editor: can also add, edit and delete rows

On a private bucket there is a third option, No access. Owners always have full access. Admins can set access for Members; only the Owner can change an Admin's access. Changing columns and bucket settings stays with Owners and Admins whatever the grant. See User Roles for the full model.

Charts

You can chart bucket data directly to see trends and aggregations without exporting to another tool.

1Click "Graph" in the grid toolbar
2Choose a chart type: Bar, Line, Pie or Scatter (Tavnit marks the best fit for your data)
3Pick the field to group by, and whether to count rows or aggregate a numeric field (sum, count, average, minimum or maximum)
4Optionally sort, limit to the top 5, 10, 15 or 20, and set a title, color theme, legend and grid
5Preview it, then click "Download as PNG" to keep it

Large Buckets

Charts use every row for Buckets of up to 10,000 rows. Above that, Tavnit charts a sample of about 10,000 rows and tells you so. Charts are not saved with the bucket: download the PNG if you need it later.

Import & Export

Import CSV / Excel

Choose “Insert” → “Import CSV / Excel” and pick a .csv, .xlsx or .xls file. Tavnit matches file columns to Bucket columns by name; for the rest you can map each one to an existing column, create it as a new column, or skip it, then click “Import” (or “Create & Import”).

Export to CSV

“Export” downloads every row in the Bucket as a CSV file, regardless of the filters on screen. Useful for sending data to other tools or keeping an offline backup.

Buckets API

Two endpoints work with your API key (X-API-Key header). Both require bucket_id and bucket_name.

Endpoint	What it does
`POST /api/buckets/write`	Adds rows (overwrite: false) or replaces the table's rows (overwrite: true). Up to 50,000 rows per request.
`GET /api/buckets/read`	Returns the columns and a page of rows, with total_count and has_more. Use limit (default 100, max 1,000) and offset to page.

Full request and response examples are on the API page.

Troubleshooting

Problem	What to check
The grid says it is read-only	You have view-only access. Ask an Owner or Admin to give you Editor access on this Bucket.
An API write is rejected with a column mismatch	A row uses a column name the Bucket doesn't have. Compare your keys with the Schema tab.
An API call is rejected with a bucket mismatch	bucket_name doesn't match the Bucket for that bucket_id. Copy both again from the details page.
A flow runs but no rows appear	Check that Bucket Export is on for the flow and that its fields are mapped to columns. Only successful runs export.
The Chat button is missing	Bucket chat is enabled per organisation; contact support.
Chat says it isn't ready	Enable Prompting on at least one text column first.