将包含 JSON 文件的文件夹转换为 SQL 表

文件夹连接器 · JSONL 文件夹

将包含 JSON 行文件的文件夹转换为 SQL 表 您可以在任何地方进行查询

将查询流代理指向该文件夹。它会在自己的计算机上读取文件，并在本地缓存中构建表，并随着文件的到达、更改或删除而保持表的更新。您可以从 Excel、Google Sheets、Nova、Claude 或 REST API 查询这些表。无需上传任何文件，也无需转换或编辑任何文件。

大约15分钟 无需编程 文件保留在您的网络上 免费计划涵盖了它

你最终会得到什么

最终你会得到一个由你命名的 SQL 表，它保存文件夹中每个 JSONL 文件的每一行。如果你把它命名为 活动你查询 文件集.事件嵌套对象会被扁平化成列，层数范围由您选择；更深层的嵌套值会保留为 JSON 文本；每一行都包含一个值。 源文件 这样您就能知道它来自哪个文件。如果文件夹中混合了不同格式的文件，您可以为每种格式创建一个表。代理程序会在自己的计算机上读取文件夹，并将数据行缓存到加密的本地存储中，然后将其作为 SQL 提供给 Excel、Google Sheets、查询生成器或任何其他客户端。文件始终保留在您的网络中。

每个表都位于一个名为“schema”的模式中。 文件集。 和 一个固定布局默认情况下，你会得到一个以……命名的表。 表名 例如，你输入。 文件集.事件包含每个匹配文件的行。嵌套对象向下依次变为列。 扁平深度默认深度为 2，更深的层级将以 JSON 文本的形式返回。每一行都包含 源文件 以及稳定的 _row_id.

和 每个布局一张桌子每个不同的形状都会成为自己的表格，最多 25 个，表格名称以其文件名中共享的部分命名，并去掉末尾的数字。文件 orders_2026_01.jsonl 至 orders_2026_03.jsonl 变得 文件集.订单如果没有可用内容，则使用表格名称。布局固定期间名称不会更改，并且不会自动将布局堆叠在一起。

每个文件夹连接器还会提供记账表格。 文件, 文件事件, 目录, 目录快照 和 卷.

它的价值所在：

• 查询以 JSON 行形式写入的应用程序事件导出文件或 LLM 对话日志，可在 Excel 或 Google Sheets 中查看。
• 无需为每个文件编写脚本，即可统计和筛选一天内 JSONL 文件中的事件。
• 当供应商更改其发送的字段时，为每个导出格式创建一个单独的表格。

你需要准备什么

查询流帐户

所有套餐（包括免费套餐）都包含文件夹连接器。免费套餐是永久有效的，并非试用期。文件夹可容纳的文件数量没有上限。

代理程序，2.6.0 或更高版本

安装在可以打开该文件夹的计算机上：文件服务器本身、办公计算机或文件所在的计算机。旧版代理程序会将文件夹卡片显示为灰色并带有“显示错误”字样。 代理 2.6.0+ 徽章。支持 Windows、Mac 或 Linux 系统。

代理程序看到的文件夹路径

本地路径或网络共享，写作 \\服务器\共享\文件夹. 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 或 /媒体, a Mac under /Volumes).

分五步完成设置

1. 在可以打开该文件夹的计算机上安装代理程序

   登录，打开 下载然后在能够打开包含 JSON 行文件的文件夹的计算机上安装系统代理：例如文件服务器或任何可以访问共享文件夹的常开计算机。安装过程只需一分钟，安装完成后即可自动运行。您需要 2.6.0 或更高版本；下载页面始终提供最新版本。

   为什么使用小型程序而不是驱动程序？ 该代理程序只需安装一次，即可在 Windows、Mac 或 Linux 系统上运行（Windows 系统下约 85 MB，Mac 和 Linux 系统下略超过 100 MB）。它会打开一个与查询流的加密出站连接，这是它唯一需要的网络路径：无需打开入站端口，也无需 VPN。它会读取自身所在的文件夹，因此文件不会移动，只有查询返回的行数据才会通过互联网传输到您端的插件、浏览器或 AI 客户端。

   下载页面显示 您的访问密钥当代理提示时，将其粘贴到代理中，然后等待徽章读取。 已连接到查询流这是你在代理人的电脑上唯一要做的事情；其他所有操作都在你的浏览器中进行。

   完整攻略（如果您需要）： Windows, 苹果, Linux.

2. 将其指向包含 JSON 行文件的文件夹

   返回浏览器打开 数据 → 数据代理找到您刚刚安装的代理，然后单击其 添加连接器 按钮。打开 文件和文件夹 药丸和选择 JSONL文件夹 卡片。不确定哪张卡片合适？选择一张。 文件夹中的文件 相反：代理程序会扫描文件夹，在“我们发现了什么”页面上列出文件夹的内容，并为您打开预先填充好的正确卡片。

   巫师跑 文件夹 → 检查 → 设置 → Realm → 查看。 在 文件夹:

   根文件夹

   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.

   扫描子文件夹，最大深度

   默认情况下，开启并有 8 个级别。

   包含模式，排除模式

   哪些文件有效？包含模式以该卡的正确通配符开头。一个连接器读取一种文件类型：包含 CSV 文件的文件夹。 和 Parquet 文件是同一个文件夹中有两个连接器，每种类型一个。

   跟随符号链接和连接点

   默认关闭。除非您启用此功能，否则代理程序不会遵循快捷方式或云端占位符。

   在可以打开该文件夹的计算机上安装 Query Streams Agent。它需要 Agent 2.6.0 或更高版本。从该 Agent 的 添加连接器 按钮，打开 文件和文件夹 并选择 JSONL文件夹 卡片。

   • 根文件夹：代理计算机上要扫描的文件夹，每行一个。网络共享类型为 \\服务器\共享\文件夹不是映射的驱动器盘符。
   • 包含模式 开始时 **/*.jsonl如果您的文件使用其他扩展名，请添加相应的模式。
   • 表名 必填项。请输入名称，例如： 活动.
   • 扁平深度：嵌套对象中最多有多少层会作为列显示。默认值为 2，范围为 1 到 8。更深层的嵌套值将以 JSON 文本的形式显示。
   • 表格布局： 离开 一个固定布局（默认） 当所有文件共享同一布局时，例如重复导出时。选择 每个布局一张桌子 对于手工组装的文件夹，每个不同的布局都有自己的表格，最多可达 25 个。

3. 查看它将建造什么

   在 查看 代理程序读取最多 64 个文件的样本，并显示它将要构建的内容。目前尚未创建任何内容。按钮显示： 测试连接 在判决结果出来之前， 下一页; 再次测试 更改设置后，程序会重新运行样本。您将看到以下四个标题之一：

   准备创建

   每个抽样文件都符合要求。文件下方的芯片显示了可访问的文件夹数量、文件和行数，以及将要存在的表。

   准备好了，附上笔记

   部分文件将被搁置，或者布局嗅探将被拒绝。琥珀色横幅会明确指出具体是哪些文件：“{n} 个文件（共 {m} 个）将被搁置”。 找出需要哪些文件以及原因 列表中，“您仍然可以创建它——连接器将不断重新检查并在其清单选项卡上报告原因。”

   需要关注

   代理程序离线或缺少文件夹。请先解决此问题再继续；代理程序离线时，页面会显示此提示，但您仍然可以继续操作。

   “此文件夹包含{n}种不同的文件布局。” 天蓝色面板表示采样文件并非全部共享同一组列。 表格布局 默认值 一个固定布局它要求每个文件都匹配。点击 切换到每个布局一张桌子 每个布局都会变成自己的表格（最多 25 个）。

   被拒绝或搁置的文件不会阻止您：点击 下一页完成向导后，稍后再修复异常文件。只有代理程序离线或文件夹缺失才会导致向导停止。

   在 查看代理程序读取最多 64 个文件的样本，并显示文件数量、大小、行数估计值以及它将要构建的表。目前尚未创建任何内容。此数据源最常报告的情况是混合形状。如果样本包含多个布局，则 表格布局 文件夹仍然处于固定状态，蓝色面板显示“此文件夹包含 3 种不同的文件布局”，并解释说，一种固定布局要求所有文件都使用同一种布局。点击 切换到每个布局一张桌子 每个形状都成为它自己的表格。代理无法以 JSONL 格式读取的文件显示在下方。 找出需要哪些文件以及原因 已预留一部分，其余部分仍在加载。您可以通过两种方式创建连接器；它会不断重新检查并在其页面上报告原因。 显现 标签。

4. 选择扫描频率，然后创建它

   默认值 设置 适用于每天接收少量文件的文件夹。以下四点您可能需要更改：

   扫描间隔

   每小时 默认情况下，扫描频率为每 5 分钟一次，也可选择每天一次。每次扫描都会比较文件大小和修改时间，以查找新增、已更改和已消失的文件。

   监视文件夹更改（近乎实时）

   默认关闭。启用后，代理程序会在几秒内响应本地磁盘；对于网络共享，响应速度会尽力而为，计划扫描仍是保证响应速度的手段。 静默期 （15 秒）等待文件写入完成。

   请刷新页面后再回答查询

   默认关闭。开启后，如果上次扫描时间早于查询时间，查询将首先重新扫描。 陈旧窗口 （60秒），最多等待 查询等待限制 （5 秒）。这适用于人员和插件，不适用于警报轮询。

   文件消失时

   删除它的行 默认情况下，或者 保留行，标记已删除（墓碑标记）。 这 消失的保护比率 （0.5）拒绝一次性丢失一半以上文件的扫描，并保留之前的库存，这就是离线共享的样子。

   然后选择 数据领域 检查行数是否计入统计。 审查 并点击 创建连接器首次扫描立即开始。连接器的 显现 该选项卡显示它生成的内容以及它保存的任何文件。

5. 看看你的表格

   打开连接器： 显现 该选项卡列出了它创建的表格。 查询生成器 同样的桌子摆放在下面 文件集 模式。三个第一天就能运行的查询：

   每个 JSONL 文件的行数

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

   每个文件一行，因此您可以查看每个 JSONL 文件贡献了多少行。

   过去一天内发生更改的文件

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

   特工看到的自昨天以来发生更改的文件，按最新文件在前排列。

   文件被搁置或拒绝的原因

   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

   删除所有行的文件，并详细说明原因，包括包含新形状的文件。

   每个文件夹连接器也都服务于相同的记账表，所有这些表都在…… 文件集 模式：

   桌子	它包含什么
   文件	文件夹中当前所有文件的概览：路径、名称、扩展名、大小、创建和修改时间、首次和最后访问时间。 files_current它还会保留已消失的文件。
   文件事件	变更历史记录：每行记录一个文件。 出现， 曾是 修改的, 消失了被搁置一旁（漂移）或曾是 拒绝，随着时间推移 事件以及它是如何被注意到的 检测到 原因在于 细节.
   目录, 目录快照, 卷	文件夹数量和大小、它们的增长方式，以及根目录所在的磁盘或共享文件夹。
   源文件, _row_id	每行数据包含两列：该行数据来自哪个文件，以及该文件内的一个固定行 ID。按以下方式分组 源文件 比较文件。

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 文件夹 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.

到处使用

连接器是查询流中的数据源，与其他数据源类似。只需在查询流中保存一次即可。 查询生成器 （该数据库方言为 DuckDB），并可从以下位置使用它：

在 Excel

该插件的 流式查询 将行拖放到工作表中，然后单击即可重新运行。 在 Excel 中运行 SQL.

谷歌工作表

这 查询流 插件会填充您选择的标签页。 用于 Google Sheets 的 Power Query.

Claude、Cursor 和其他人工智能客户端

通过 Query Streams MCP 服务器，Claude 了解文件夹模型，包括 源文件 和 文件事件. 通过 MCP 与 Claude 共享 JSONL 文件夹.

REST API

在每个计划中，任何已保存的查询都会成为一个具有自己键的只读端点。 JSONL 文件夹 REST API.

诺瓦

请用通俗易懂的英语询问商业计划书；Nova 可以根据其内置描述识别每个文件夹、表格和列。

自动化

按计划将行同步到 Airtable、Smartsheet、Baserow、SeaTable 或工作表。 自动化指南.

文件夹表也可以连接到您的其他连接器：联合查询可以匹配 源文件 在同一代理上，将 JSON 行文件文件夹中的名称或订单 ID 与数据库中的名称或订单 ID 进行比对。

新建、更改和删除的文件如何显示

被搁置的文件

在“检查”步骤和“清单”选项卡上会出现三个词。它们的含义各不相同：

停放在一旁（停放）

文件与固定布局不符，或者文件无法读取、撕裂、锁定或超出限制。每个文件要么全部占用，要么全部不占用：已停放的文件不贡献任何行。 文件事件 记录 漂移 行 细节 指定文件名和列名。如果文件大小和修改时间保持不变，则跳过该文件；一旦文件大小和修改时间发生变化，则立即重试。

无法阅读

代理程序无法打开或解析该文件，因为它的类型是：不是真正的工作簿，被其他程序锁定，是云端占位符，或是无法解码的字节。它自行停止运行，文件夹的其他部分继续处理。只有当文件夹内没有任何可读文件时，代理程序才会拒绝整个文件夹的处理。

拒绝

代理程序无法固定任何布局，例如，因为文件对列类型存在冲突。目前尚无数据表。 文件事件 获得 拒绝 与原因争吵 细节代理程序会在每次扫描时重试，直到布局固定为止。修复或排除它所指的文件，消息就会消失。

在哪里看：琥珀色的横幅 查看 (找出需要哪些文件以及原因），连接器的 显现 后面跟着制表符。在 SQL 中： SELECT relative_path, event_type, detail FROM fileset.files_events WHERE event_type IN ('drift','refused') ORDER BY event_at DESC.

值得了解的界限

文件夹数量或文件数量没有计划限制。与其他连接器一样，这些行也会计入您的数据域。您可以提高或降低连接器的默认设置：

内容上限是指文件会被暂存而不是截断：每个文件最多 2,000,000 行或 512 MiB，每次扫描最多 10,000,000 行或 2 GiB。一个文件夹最多可以容纳 25 种不同的布局。 每个布局一张桌子 模式。

人们提出的问题

• 文件系统
• CSV文件夹
• 镶木地板文件夹
• Excel文件夹
• SQLite文件夹
• 多记录 CSV
• 机器日志
• Web服务器日志
• 容器日志
• 应用程序日志
• 系统日志
• 自定义日志