FILESTREAM INSERT 必须在显式事务中执行，否则文件系统无响应；支持 NULL（不创建文件）、0x（创建空文件）和 CAST 值（写入内容）三种输入形态，且依赖 FILESTREAM 文件组配置。
INSERT 操作在含 FILESTREAM 列的表中，不能像普通 varbinary(max) 列那样直接传入大二进制块——它表面是 SQL 语句，背后会触发文件系统级动作。你必须确保事务上下文、NULL 处理和数据形态三者匹配，否则会静默失败或创建空文件。
FILESTREAM INSERT 必须在显式事务中执行
哪怕只插一条记录，INSERT 也必须包裹在 BEGIN TRANSACTION / COMMIT 中。FILESTREAM 引擎需要事务标记来绑定数据库行与文件系统文件。不加事务时，SQL Server 可能返回成功，但文件系统里什么都不会生成，file_stream 列值显示为 NULL 或 0x（空字节），且后续无法通过 PathName() 获取有效路径。
- 错误写法：
INSERT INTO Archive.dbo.Records VALUES (NEWID(), 1, NULL);—— 看似成功，但无事务，FILESTREAM 文件不会创建（即使列允许 NULL） - 正确写法：
BEGIN TRANSACTION;<br>INSERT INTO Archive.dbo.Records VALUES (NEWID(), 1, NULL);<br>COMMIT;
- 注意：
GET_FILESTREAM_TRANSACTION_CONTEXT()不需要在纯INSERT场景中显式调用；它仅在 Win32 流操作（如OpenSqlFilestream）前必需
NULL、空字节、真实数据三种值的行为差异
file_stream 列接受三种典型输入，每种对应完全不同的文件系统结果：
-
NULL：数据库引擎**不创建**任何文件系统文件，PathName()返回NULL，适合占位元数据但暂无内容的场景 -
CAST('' AS VARBINARY(MAX))（即0x）：创建一个**长度为 0 的文件**，文件存在但为空，可用于后续用 Win32 打开句柄写入（例如流式上传） -
CAST('Seismic Data' AS VARBINARY(MAX))：创建完整文件并写入内容，文件大小等于二进制长度，适用于中小尺寸（≤1 MB）一次性写入
插入前必须确认 FILESTREAM 文件组已就绪
即便 INSERT 语法完全正确，若底层配置缺失，SQL Server 会报错 Msg 5505, Level 16（“The filegroup 'xxx' does not have a file that is designated for FILESTREAM data.”）。这不是语法问题，而是部署缺陷：
- 检查数据库是否含 FILESTREAM 文件组：
SELECT name, type_desc FROM sys.filegroups WHERE type = 'FD'，结果应至少有一行type_desc = 'FILESTREAM_DATA_FILEGROUP' - 确认该文件组下有实际文件：
SELECT name, physical_name FROM sys.database_files WHERE type = 2（type = 2表示 FILESTREAM 文件） - 常见疏漏：只在实例级别启用了 FILESTREAM（via SQL Server Configuration Manager），但没在数据库中添加 FILESTREAM 文件组，或忘了用
ALTER DATABASE ... ADD FILEGROUP ... CONTAINS FILESTREAM
大文件插入不要用纯 T-SQL INSERT
当你要插入 >1 MB 的文件（比如视频、CAD 图纸），直接用 CAST(... AS VARBINARY(MAX)) 在 INSERT 中拼接，会把整个文件加载进客户端内存和 SQL Server 网络缓冲区，极易超时、OOM 或触发 max text repl size 限制。这不是性能差的问题，是架构误用。
- 正确路径：用
PathName()+GET_FILESTREAM_TRANSACTION_CONTEXT()获取路径和事务令牌，再用 Win32OpenSqlFilestream()打开句柄，最后调用WriteFile()流式写入 - T-SQL
INSERT只适合 ≤100 KB 的小数据；超过 1 MB 就该切到流模式 - 容易被忽略的一点：流写入后必须调用
FlushFileBuffers()，否则事务提交时可能丢失最后一批数据
sys.database_files 和 PathName() 返回值三层交叉验证。 
