Turn a Folder of JSON Files Into SQL Tables

Folder connector · JSONL Folder

Turn a folder of JSON lines files into SQL tables you can query anywhere

Point the Query Streams Agent at the folder. It reads the files on its own computer, builds the tables in a local cache there and keeps them current as files arrive, change or disappear. You query them from Excel, Google Sheets, Nova, Claude or the REST API. Nothing is uploaded and no file is converted or edited.

About 15 minutes No coding needed Files stay on your network The Free plan covers it

What you’ll end up with

You end up with one SQL table, named by you, that holds every line of every JSONL file in the folder. If you call it events, you query fileset.events. Nested objects are flattened into columns down to the depth you choose, deeper values are kept as JSON text, and every row carries _source_file so you know which file it came from. If the folder mixes files of different shapes, you can have one table per shape instead. The Agent reads the folder on its own computer and caches the rows there in an encrypted local store, then serves them as SQL to Excel, Google Sheets, the Query Builder or any other client. The files stay on your network.

Every table sits in one schema named fileset. With One pinned layout, the default, you get one table named by the Table name you type, for example fileset.events, holding the rows of every matched file. Nested objects become columns down to Flatten depth, 2 by default, and anything deeper lands as JSON text. Every row carries _source_file and a stable _row_id.

With One table per layout, each distinct shape becomes its own table, up to 25, named after the shared part of its file names with trailing numbers trimmed. Files orders_2026_01.jsonl to orders_2026_03.jsonl become fileset.orders. If nothing usable remains, the Table name is used. Names never change while the layout is pinned, and there is no automatic view that stacks the layouts together.

Every folder connector also gives you the bookkeeping tables files, files_events, directories, directory_snapshots and volumes.

Where it earns its keep:

• Query application event exports or LLM conversation logs written as JSON lines, in Excel or Google Sheets.
• Count and filter events across a day’s worth of JSONL files without a script per file.
• Give each export shape its own table when a vendor changes the fields it sends.

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).

Set it up in five steps

1. Install the Agent on a computer that can open the folder

   Sign in, open Download, and install the Agent for your system on the computer that can open a folder of JSON lines files: the file server, or any always-on computer that can reach the share. It takes a minute and starts on its own from then on. You need version 2.6.0 or later; the Download page always has the current one.

   Why a small program instead of a driver? The Agent is one install for Windows, Mac or Linux (about 85 MB on Windows, a little over 100 MB on Mac and Linux). It opens one outbound encrypted connection to Query Streams and that is the only network path it needs: no inbound port to open, no VPN. It reads the folder where it sits, so the files stay put and only the rows a query returns travel across the internet to the add-in, browser or AI client on your side.

   The Download page shows Your Access Key. Paste it into the Agent when it asks, and wait for the badge to read Connected to Query Streams. That is the only thing you do on the Agent’s computer; everything else happens in your browser.

   Full walkthroughs if you want them: Windows, Mac, Linux.

2. Point it at a folder of JSON lines files

   Back in your browser open Data → Data Agents, find the Agent you just installed and click its Add connector button. Open the Files & Folders pill and pick the JSONL Folder card. Not sure which card fits? Pick Files in a folder instead: the Agent samples the folder, names what it holds on a “What we found” page and opens the right card for you, pre-filled.

   The wizard runs Folders → Check → Settings → Realm → Review. On Folders:

   Root folders

   One path per line, as the Agent’s computer sees it. Each folder shows a status (reachable, denied, missing, unreachable, credentials invalid or not mounted) as soon as you add it. On a Windows Agent a share that needs a login gets one from the folder’s Credential column, stored once per server; on Linux or a Mac, mount the share first.

   Scan subfolders, Max depth

   On, and 8 levels, by default.

   Include patterns, Exclude patterns

   Which files count. The include pattern starts with the right glob for this card. One connector reads one file type: a folder with CSV and Parquet files is two connectors on the same folder, one per type.

   Follow symlinks and junctions

   Off by default. The Agent does not follow shortcuts or cloud placeholders unless you turn this on.

   Install the Query Streams Agent on a computer that can open the folder. It needs Agent 2.6.0 or later. From that Agent’s Add connector button, open Files & Folders and pick the JSONL Folder card.

   • Root folders: the folders on the Agent computer to scan, one per line. Type network shares as \\server\share\folder, not a mapped drive letter.
   • Include patterns starts as **/*.jsonl. Add a pattern if your files use another extension.
   • Table name is required. Type a name such as events.
   • Flatten depth: how many levels of nested objects become columns. Default 2, range 1 to 8. Deeper values land as JSON text.
   • Table layout: leave One pinned layout (default) when all files share one layout, as with recurring exports. Choose One table per layout for folders people assemble by hand, where each distinct layout gets its own table, up to 25.

3. Check what it will build

   On Check the Agent reads a sample of up to 64 files and shows what it will build. Nothing is created yet. The button reads Test connection until a verdict exists, then Next; Test again re-runs the sample after you change something. You will see one of four headlines:

   Ready to create

   Every sampled file fits. The chips under it say how many folders were reachable, how many files and rows, and which tables will exist.

   Ready, with notes

   Some files will be set aside, or the layout sniff refused. An amber banner says exactly which: “{n} of {m} file(s) will be set aside” with a Show which files and why list, and “You can create it anyway — the connector will keep re-checking and reports the reason on its Manifest tab.”

   Needs attention

   The Agent is offline or a folder is missing. Fix that before going on; with the Agent offline the page says so and still lets you continue.

   “This folder holds {n} different file layouts.” A sky-blue panel means the sampled files do not all share one set of columns. Table layout defaults to One pinned layout, which expects every file to match. Click Switch to one table per layout and each layout becomes its own table instead (up to 25).

   A refusal or set-aside files never block you: click Next, finish the wizard and fix the odd files later. Only an offline Agent or a missing folder stops the wizard.

   On Check, the Agent reads a sample of up to 64 files and shows the file count, size, row estimate and the table it will build. Nothing is created yet. The thing this source most often reports is mixed shapes. If the sample holds several layouts while Table layout is still pinned, a blue panel says “This folder holds 3 different file layouts” and explains that one pinned layout expects every file to share one layout. Click Switch to one table per layout and each shape becomes its own table. Files the Agent could not read as JSONL appear under Show which files and why as set aside, and the rest still load. You can create the connector either way; it keeps re-checking and reports the reason on its Manifest tab.

4. Choose how often it scans, then create it

   The defaults on Settings suit a folder that receives a few files a day. Four you may want to change:

   Scan interval

   Every hour by default; choose from every 5 minutes to daily. Each sweep compares size and modified time to find new, changed and vanished files.

   Watch folder for changes (near real-time)

   Off by default. On, the Agent reacts within seconds on local disks; on network shares it is best-effort and the scheduled scan remains the guarantee. Quiet period (15 seconds) waits for a file to finish being written.

   Refresh before answering a query

   Off by default. On, a query first re-scans when the last scan is older than the Staleness window (60 seconds), waiting at most the Query wait limit (5 seconds). It applies to people and add-ins, not to alert polling.

   When a file vanishes

   Drop its rows by default, or Keep rows, mark deleted (tombstone). The Vanish guard ratio (0.5) refuses a scan that loses more than half the files at once and keeps the previous inventory, which is what an offline share looks like.

   Then pick the Data Realm the rows count against, check Review and click Create connector. The first scan starts right away. The connector’s Manifest tab shows what it built and any file it set aside.

5. Look at your tables

   Open the connector: the Manifest tab lists the tables it built. In the Query Builder the same tables sit under the fileset schema. Three queries that work on day one:

   Rows per JSONL file

   SELECT _source_file, COUNT(*) AS row_count
   FROM fileset.events
   GROUP BY _source_file
   ORDER BY row_count DESC
   LIMIT 100

   One row per file, so you can see how many lines each JSONL file contributed.

   Files that changed in the last day

   SELECT relative_path, size_bytes, modified_utc
   FROM fileset.files
   WHERE modified_utc >= now() - INTERVAL 1 DAY
   ORDER BY modified_utc DESC
   LIMIT 100

   The files the Agent saw change since yesterday, newest first.

   Files set aside or refused, and why

   SELECT relative_path, event_type, detected_by, detail, event_at
   FROM fileset.files_events
   WHERE event_type IN ('refused', 'drift')
   ORDER BY event_at DESC
   LIMIT 20

   Every file whose lines were left out, with the reason in detail, including a file with a new shape.

   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.

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.

When a folder is not reachable

Every folder on the Folders step shows a status as soon as you add it. Hover the status to read the Agent’s own message; its first words say which case it is.

Use it 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.

Google Sheets

The Query Streamer add-on fills a tab you pick. Power Query for Google Sheets.

Claude, Cursor and other AI clients

Through the Query Streams MCP server; Claude knows the folder model, including _source_file and files_events. JSONL Folder with Claude via MCP.

REST API

Any saved query becomes a read-only endpoint with its own key, on every plan. JSONL 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 JSON lines files against a database on the same Agent.

How new, changed and deleted files show up

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_events records a drift row whose detail names 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_events gets a refused row with the reason in detail, 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.

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:

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

• File System
• CSV Folder
• Parquet Folder
• Excel Folder
• SQLite Folder
• Multi-record CSV
• Machine Logs
• Web Server Logs
• Container Logs
• Application Logs
• System Logs
• Custom Logs