Turn any folder of files into SQL tables that stay current
Thirteen folder connectors, one idea: point the Query Streams Agent at a folder on your own network and it builds the tables, tags every row with the file it came from, and keeps them current as files arrive, change or disappear. Query them from Excel, Google Sheets, Nova, Claude or the REST API. Nothing is uploaded, converted or edited.
Pick the guide for your files
Each card below is one connector and one guide. Every guide walks the same five steps — install the Agent, point it at the folder, check what it will build, choose how often it scans, look at your tables — and then shows the tables, queries and gotchas that are specific to that file type. Not sure which fits? In the Portal pick Files in a folder: the Agent samples the folder and opens the right card for you.
File System
a queryable inventory of every file under your folders, with sizes, dates, a change history and folder growth, without reading file contents.
CSV Folder
every CSV in the folder merged into one table, or one table per layout, with each row tagged with the file it came from.
Parquet Folder
a folder of Parquet files as one typed table, with columns and types taken from the file footers.
Excel Folder
every workbook’s sheets merged into one table per sheet, such as data_orders, or one table per layout for mixed workbooks.
SQLite Folder
many SQLite files queried as one database, with same-named tables merged and every row tagged with its file.
Multi-record CSV
one table per record type, such as data_hdr and data_itm, joinable by file and sequence number.
Machine Logs
CNC, PLC and robot logs tailed into an events table, plus alarm, cycle and downtime tables for supported controllers.
Web Server Logs
one row per request from nginx, Apache, IIS or Caddy logs, with client IP, path, status and bytes as columns.
Container Logs
Docker container log lines as rows, with the container name, stream and message as columns.
Application Logs
JSON and text application logs as rows with level, logger and message, with stack traces kept with their event.
Custom Logs
any text log parsed into columns you describe, with unparsed lines kept in a raw lines table.
How every folder connector works
A database connector points at a server that already has tables. A folder connector points at folders on the Agent’s computer. The Agent reads the files, pins a layout from a sample of up to 64 of them, builds the tables in an encrypted local cache (one DuckDB schema, named fileset) and refreshes them on a schedule you choose. Files that do not fit the layout are set aside and reported, never silently dropped or bent into shape. One connector reads one file type; a folder with CSV and Parquet files is two connectors on the same folder.
Every folder connector also serves the same bookkeeping tables, all in the fileset schema:
| Table | What it holds |
|---|---|
files | Every file currently in the folder: path, name, extension, size, created and modified times, first and last seen. A view over files_current, which also keeps files that have vanished. |
files_events | The change history: one row per file that appeared, was modified, vanished, was set aside (drift) or was refused, with the time in event_at, how it was noticed in detected_by and the reason in detail. |
directories, directory_snapshots, volumes | Folder counts and sizes, how they grew, and the disks or shares the roots live on. |
_source_file, _row_id | Two columns on every data row: which file the row came from, and a stable row id inside that file. Group by _source_file to compare files. |
What you’ll need
A Query Streams account
Folder connectors are on every plan, including Free. Free is a plan you keep, not a trial that expires. There is no cap on how many files a folder may hold.
The Agent, 2.6.0 or later
Installed on a computer that can open the folder: the file server itself, an office computer, or the machine the files land on. An older Agent shows the folder cards greyed out with an Agent 2.6.0+ badge. Windows, Mac or Linux.
The folder’s path, as the Agent sees it
A local path, or a network share written as \\server\share\folder. The Agent runs as a service, so it cannot see drives you mapped at your login (Z: and friends). On Windows it can sign in to a share with a login you store; on Linux or a Mac, mount the share first (Linux under /mnt or /media, a Mac under /Volumes).
Where does the work happen? On the computer that runs the Agent. It scans the folder, copies the rows into an encrypted local cache there (one schema, named fileset) and runs every query against that cache. Your files are read, never modified, moved or uploaded.
Reaching a file on a network share
The Agent opens files as a background service, not as you, so a file on another computer needs one extra step. Which step depends on the computer the Agent runs on.
If the test cannot get to the share, look for these words in its result: unreachable means the Agent’s computer got no answer from the server. On Linux or a Mac, not mounted means the share still has to be mounted, and that message includes the exact mount command for your server.
Folders on a share? On Windows, one login covers every folder you add from the same server. Watch folder for changes works on a share too, on a best-effort basis; the scheduled scan is what guarantees every change is picked up.
How new, changed and deleted files show up
New and changed files
On every Scan interval (or within seconds with Watch folder on) a new file that fits the layout has its rows added and gets an appeared event. A changed file is re-read in one transaction: its old rows go, its new rows come, and it gets a modified event.
Deleted files
A file that vanishes drops its rows by default, or keeps them marked deleted if you chose the tombstone option, and gets a vanished event. If more than half the files disappear at once the scan is refused and the previous inventory stays: an offline share looks exactly like that.
Set-aside files
A file that does not fit the layout, cannot be opened, or is over a cap is set aside whole: none of its rows load, and files_events gets a drift row naming the file and the column. Fix the file and save it; the next scan tries it again.
How fresh is what I see?
Queries answer from the last scan. There is no Rescan or Sync now button; the scan interval, the folder watcher and Refresh before answering a query are the three controls. MAX(last_seen_utc) from files_current tells you when the Agent last looked.
Files that are set aside
Three words appear on the Check step and the Manifest tab. They mean different things:
- Set aside (parked)
- The file does not match the pinned layout, or is unreadable, torn, locked or over a cap. It is all-or-nothing per file: a parked file contributes zero rows.
files_eventsrecords adriftrow whosedetailnames the file and the column. The file is skipped while its size and modified time stay the same, and retried as soon as it changes. - Unreadable
- The Agent could not open or parse the file as its type: not a real workbook, locked by another program, a cloud placeholder, undecodable bytes. It parks on its own and the rest of the folder continues. Only a folder with zero readable files refuses the whole set.
- Refused
- The Agent could not pin any layout at all, for example because files disagree on a column type. No data table exists yet.
files_eventsgets arefusedrow with the reason indetail, and the Agent re-tries on every scan until a layout pins. Fix or exclude the file it names and the message clears.
Where to look: the amber banner on Check (Show which files and why), the connector’s Manifest tab afterwards. In SQL: SELECT relative_path, event_type, detail FROM fileset.files_events WHERE event_type IN ('drift','refused') ORDER BY event_at DESC.
Use the tables everywhere
The connector is a data source like any other in Query Streams. Save a query once in the Query Builder (the dialect is DuckDB) and use it from:
Excel
The add-in’s Stream a Query drops the rows into a sheet and re-runs on a click. Running SQL in Excel.
Claude, Cursor and other AI clients
Through the Query Streams MCP server; Claude knows the folder model, including _source_file and files_events. CSV Folder with Claude via MCP.
REST API
Any saved query becomes a read-only endpoint with its own key, on every plan. CSV Folder REST API.
Nova
Ask in plain English on the Business plan; Nova knows every folder table and column from its built-in descriptions.
Automations
Sync the rows to Airtable, Smartsheet, Baserow, SeaTable or a sheet on a schedule. Automation guides.
Folder tables join to your other connectors too: a federated query can match _source_file names or order ids in a folder of CSV files against a database on the same Agent.
Limits worth knowing
There is no plan limit on folders or on the number of files. The rows do count against your Data Realm like any other connector. Defaults you can raise or lower on the connector:
| Setting | Default | What it does |
|---|---|---|
| Max depth | 8 | How many folder levels below each root are scanned (1–64). |
| Max files per scan | 100,000 | Files considered in one sweep. |
| Max file size to hash | 32 MiB | Only matters with Hash file contents on. |
| Event log retention | 30 days | How long files_events rows are kept. |
| Scan parallelism per root | 2 | Folders read at once per root. |
Content caps, which park a file rather than truncate it: 2,000,000 rows or 512 MiB per file, 10,000,000 rows or 2 GiB per scan. A folder can hold at most 25 distinct layouts in One table per layout mode.
Questions people ask
Are my files uploaded anywhere?
No. The Agent reads them on its own computer and keeps the rows in an encrypted local cache there. A query runs against that cache and only the rows it returns leave the machine, over one outbound connection. Files are never modified, moved or converted.
Do I need to open a port or run a VPN?
No. The Agent makes one outbound connection on port 443 and both requests and rows travel over it. If outbound HTTPS works, this works.
Can the folder be on a network share, or in OneDrive or Dropbox?
Yes. Type a share as \\server\share\folder, because the Agent runs as a service and cannot see drives mapped at your login. On Windows, store a login for the server if the share lets in only named people; without one the Agent reads as its own service account. On Linux or a Mac, mount the share first. A synced OneDrive or Dropbox folder works when its files are stored on the computer: set the folder to Always keep on this device. The Agent does not download cloud-only files.
The folder has more than one kind of file. One connector or two?
One connector reads one file type. A folder with CSV and Parquet files is two connectors on the same root, one per type. Files that do not match the include pattern are ignored, not set aside.
Is there a Rescan button?
No. The Agent scans on the Scan interval, reacts to changes when Watch folder is on, and can re-scan before answering a query when you turn that on. Edit the connector to change any of the three.
Does the Free plan really cover this?
Yes. Free is a plan you keep, not a trial that expires. Folder connectors have no file cap of their own; the rows count against your Data Realm like any other connector. See what each plan includes on the pricing page.
Setup trouble?
- Agent shows Offline, or Test connection and Browse are greyed out? Check that the Agent is online → Is the Agent online?
English 
Spanish 
German 
French 
Portuguese 
Japanese 
Korean 
Chinese 
Italian 
Dutch 
Indonesian 
Polish