📊 DuckDB 文章质量审计报告 日期：2026-09-08

✅ 通过：100 篇 ⚠️ 警告：0 篇（无纯警告文件，所有失败均为错误） ❌ 失败：164 篇

总检查文件数：264 篇（已排除 quality_audit_report_*.md）

📋 失败详情（按错误类型分类）

1. “Only TEMPORARY table names can use the ’temp’ catalog”（最常见）

这是最多的错误类型，出现在大量文章中。原因：文章使用了 temp.* 表名引用，但 DuckDB v1.5+ 已禁止在 temp catalog 中使用非临时表名。

受影响文章（部分）：

• duckdb-152-release.md: Line 195, 292
• duckdb-153-release.md: Line 44, 119
• duckdb-ai-data-pipeline.md: Line 110, 154, 202, 249, 277, 346, 383
• duckdb-asof-joins-time-series.md: Line 56, 174, 208
• duckdb-cheapest-hardware-benchmark.md: Line 94, 173
• duckdb-clickstream-performance-tuning.md: Line 171, 222
• duckdb-competitive-intelligence-system.md: Line 44, 74
• duckdb-complete-guide.md: Line 67, 188
• duckdb-data-pipeline.md: 多处
• duckdb-filter-syntax.md: Line 83
• duckdb-gap-island-problem.md: Line 41
• duckdb-geojson-complete-guide.md: Line 137, 295
• duckdb-group-by-aggregation.md: Line 42, 335
• duckdb-housing-price-analysis-product.md: Line 97, 135
• duckdb-json-advanced-guide.md: Line 33, 207, 235
• duckdb-json-practical-workshop.md: Line 57, 123, 246
• duckdb-list-functions-complete-guide.md: Line 32, 561
• duckdb-lance-extension-guide.md: Line 74
• duckdb-merge-etl-dynamic-filters.md: Line 75, 104
• duckdb-millions-data-processing.md: Line 79
• duckdb-nested-data-list-struct-map.md: Line 194, 276
• duckdb-parquet-advanced-features.md: Line 34
• duckdb-partitioned-materialized-view-arrow-cache.md: Line 30
• duckdb-performance-tuning-5-tips.md: Line 206
• duckdb-performance-tuning-ultimate-guide.md: Line 225, 337
• duckdb-pre-aggregation-tables.md: Line 42, 122
• duckdb-predicate-pushdown-filter-indexes.md: Line 57, 194, 215
• duckdb-qualify-clause.md: Line 77, 124, 164
• duckdb-replace-clickhouse-realtime.md: Line 65, 144
• duckdb-returning-clause-etl.md: Line 63
• duckdb-return-null-on-error.md: Line 109
• duckdb-sector-rotation-monitor.md: Line 124, 181, 341
• duckdb-security-audit-2026-aug.md: Line 45
• duckdb-spatial-geometry-builtin.md: Line 76, 177
• duckdb-sql-advanced-techniques.md: Line 79, 92
• duckdb-sql-macros-guide.md: Line 41, 56, 81, 95, 118, 153, 163
• duckdb-sql-rule-engine-anomaly-detection.md: Line 244, 387
• duckdb-startup-analytics-dashboard.md: Line 62, 254
• duckdb-stock-screener.md: Line 294
• duckdb-string-functions-guide.md: Line 247, 282
• duckdb-time-series-fill.md: Line 26
• duckdb-turbovec-offline-rag-local-first.md: Line 69
• duckdb-unpivot-grouping-sets.md: Line 38, 147
• duckdb-v154-hidden-gems.md: Line 41
• duckdb-v154-new-features.md: Line 54, 153
• duckdb-v154-variegata-key-features.md: Line 89, 118, 206
• duckdb-variant-type.md: Line 66, 95
• duckdb-window-functions-business-analytics.md: Line 40, 130, 212
• duckdb-window-macro-aggregation.md: Line 22, 135
• hermes-obs-duckdb-quack-agent-observability.md: Line 55
• pg-duckdb-postgres-analytics.md: Line 99

2. “WITH WITH …” 重复 CTE 关键字

SQL 中出现了 WITH WITH cte_name AS (...) 语法错误。

受影响文章：

• duckdb-competitive-intelligence-system.md: Line 138, 300
• duckdb-cross-database-joins.md: Line 377
• duckdb-e-commerce-anomaly-detection.md: Line 104, 185
• duckdb-filter-clause.md: Line 192
• duckdb-json-nested-data.md: Line 165, 202
• duckdb-json-patch-functions.md: Line 121
• duckdb-json-wildcard-path.md: Line 66, 90
• duckdb-list-functions-nested-json.md: Line 188
• duckdb-list-pivot-mastery.md: Line 327, 392
• duckdb-marketing-data-product-framework.md: Line 91
• duckdb-multi-csv-reconciliation.md: Line 143
• duckdb-pivot-by-expression.md: Line 84, 177
• duckdb-pre-aggregation-tables.md: Line 150
• duckdb-price-monitor.md: Line 101
• duckdb-real-time-streaming-guide.md: Line 205, 405
• duckdb-sql-advanced-techniques.md: Line 158, 185, 285
• duckdb-stock-screener.md: Line 109, 138
• duckdb-time-series-fill.md: Line 55, 89, 120, 147, 194, 258
• duckdb-turbovec-offline-rag-local-first.md: Line 69
• duckdb-unpivot-grouping-sets.md: Line 241
• duckdb-v154-hidden-gems.md: Line 252
• duckdb-v154-variegata-key-features.md: Line 247

3. Python 代码：unterminated string literal（未终止的字符串字面量）

Python 代码块中存在字符串未正确闭合的问题。

受影响文章：

• duckdb-bulk-load-optimization.md: Line 166, 238
• duckdb-copy-to-export-complete-guide.md: Line 273
• duckdb-cross-database-joins.md: Line 72
• duckdb-ctas-parquet-data-product-backend.md: Line 45, 117, 193, 257
• duckdb-data-hub-attach-pattern.md: Line 88
• duckdb-dlt-evidence-pipeline.md: Line 66, 375
• duckdb-ecommerce-automated-monitoring-dashboard.md: Line 118, 166
• duckdb-ecommerce-daily-report.md: Line 87, 148
• duckdb-ecommerce-profit-analyzer-saas.md: Line 153, 202, 258
• duckdb-ecommerce-sales-engine.md: Line 32, 203
• duckdb-ecommerce-weekly-report-automation.md: Line 179, 219
• duckdb-financial-reconciliation.md: Line 196
• duckdb-financial-signal-engine.md: Line 232
• duckdb-industry-report-saas.md: Line 241
• duckdb-json-auto-parse.md: Line 273
• duckdb-json-functions-mastery.md: Line 259
• duckdb-materialized-view-basics.md: Line 174
• duckdb-mcp-server-guide.md: Line 107, 161
• duckdb-parquet-metadata-data-quality.md: Line 104, 166, 290
• duckdb-partition-by-complete-guide.md: Line 186, 314
• duckdb-partitioned-materialized-view-arrow-cache.md: Line 157, 270
• duckdb-personal-data-product.md: Line 51, 213
• duckdb-pivot-by-expression.md: Line 105
• duckdb-portfolio-tracker.md: Line 68, 136, 223, 308
• duckdb-pos-report-automation.md: Line 77, 149
• duckdb-price-comparison-engine.md: Line 70, 112, 250
• duckdb-price-monitor.md: Line 170
• duckdb-python-guide.md: Line 472
• duckdb-query-remote-files.md: Line 149
• duckdb-real-time-streaming-guide.md: Line 301
• duckdb-replace-clickhouse-realtime.md: Line 211
• duckdb-sqlite-lightweight-bi.md: Line 53, 112
• duckdb-stock-analysis-automation.md: Line 43, 129, 156, 204, 275, 314, 339
• duckdb-stock-screener.md: Line 197
• duckdb-turbovec-high-performance-vector-search.md: Line 144
• duckdb-turbovec-vs-pinecone-cost-analysis.md: Line 54, 163
• duckdb-vs-pandas-10gb-benchmark.md: Line 73, 90, 123, 143, 184, 215, 266, 284, 431
• duckdb-window-macro-aggregation.md: Line 195
• duckdb-zero-etl-daily-report.md: Line 145, 187, 248, 332
• duckdb-v15-variegata.md: Line 180, 307
• duckdb-dbt-monetization-toolchain.md: Line 282
• duckdb-e-commerce-anomaly-detection.md: Line 279

4. SQL 语法错误（其他类型）

INSERT OR REPLACE / INSERT OR REPLACE BY NAME：

• duckdb-153-release.md: Line 142 — INSERT OR REPLACE BY NAME INTO employees 语法错误

SHOW SCHEMAS FROM / SHOW ALL LIKE：

• duckdb-154-release.md: Line 103 — SHOW SCHEMAS FROM uc 语法错误
• duckdb-delta-unity-catalog-complete-guide.md: Line 85 — 同上

Qualified column names in UPDATE .. SET：

• duckdb-154-release.md: Line 138
• duckdb-upcoming-v2-roadmap-preview.md: Line 51

CREATE PROJECTION（不支持）：

• duckdb-explain-analyze.md: Line 108 — CREATE PROJECTION sales_date_idx ON sales (sale_date)

CREATE EXTENSION（不支持）：

• duckdb-ecommerce-competitor-monitoring-service.md: Line 150 — CREATE EXTENSION fuzzy
• duckdb-production-deployment-guide.md: Line 270 — CREATE EXTENSION IF NOT EXISTS postgres_fdw

不支持的 ROWS_PER_GROUP 选项：

• duckdb-copy-to-export-complete-guide.md: Line 66, 78, 216
• duckdb-partition-by-complete-guide.md: Line 110, 261
• duckdb-partition-pruning-production-guide.md: Line 231

不支持的 OVERWRITE_MODE 选项：

• duckdb-partition-by-complete-guide.md: Line 169

NameListToString NOT IMPLEMENTED：

• duckdb-ai-data-lake-lance-iceberg.md: Line 88
• duckdb-delta-unity-catalog-complete-guide.md: Line 103, 123

read_json_auto geojson 参数无效：

• duckdb-geojson-complete-guide.md: 多处 — geojson=true 不是有效参数

GROUP BY GROUPING SETS 语法错误：

• duckdb-group-by-aggregation.md: Line 263, 281
• duckdb-unpivot-grouping-sets.md: Line 208, 217, 226

PARTITION BY / PARTITION_BY 语法错误：

• duckdb-iceberg-writes-catalog.md: Line 88, 238
• duckdb-parquet-performance-guide.md: Line 180
• duckdb-real-time-streaming-guide.md: Line 279
• duckdb-startup-analytics-dashboard.md: Line 325

LOAD DATA FROM（非 DuckDB 语法）：

• duckdb-145-lts-andium.md: Line 105 — LOAD DATA FROM 'batch_001.csv'

CONNECT 语法（非 DuckDB 支持）：

• duckdb-connect-uri-ephemeral-attach.md: Line 26, 49, 62, 107, 126, 184

UI server not started：

• duckdb-builtin-ui.md: Line 56

duckdb -dark-mode（shell 命令被当作 SQL）：

• duckdb-v154-variegata-key-features.md: Line 27
• duckdb-quack-protocol.md: Line 198

STRPOS 参数数量错误：

• duckdb-string-functions-guide.md: Line 34 — STRPOS('ORD-2026-001', '-', 4) 只接受 2 个参数

.. 省略号语法（不是合法 SQL）：

• duckdb-ai-data-lake-lance-iceberg.md: Line 177
• duckdb-clickstream-performance-tuning.md: Line 36
• duckdb-gap-island-problem.md: Line 118, 148, 168
• duckdb-lance-extension-guide.md: Line 109, 253, 275
• duckdb-list-functions-complete-guide.md: Line 149
• duckdb-merge-idempotent-etl.md: Line 44
• duckdb-merge-into-production-guide.md: Line 36, 227, 284
• duckdb-ml-inference-infera.md: Line 403, 432
• duckdb-predicate-pushdown-filter-indexes.md: Line 119
• duckdb-qualify-clause.md: Line 216, 252, 269
• duckdb-security-audit-2026-aug.md: Line 85
• duckdb-window-functions-complete.md: Line 32（中文占位符）

{{ }} Jinja/DBT 模板语法被当作 SQL 解析：

• duckdb-dbt-data-modeling.md: Line 245, 270, 298, 327, 385, 414, 460
• duckdb-dbt-monetization-toolchain.md: Line 158, 176, 205
• duckdb-dbt-report-automation.md: Line 134, 153, 183
• duckdb-serverless-report-saas.md: Line 107, 125, 143

read_duckdb 函数签名不匹配：

• duckdb-read-duckdb-merge.md: 多处 — 使用了不支持的双参数形式

UNPIVOT … INTO 语法错误：

• duckdb-list-pivot-mastery.md: Line 238
• duckdb-pivot-long-to-wide.md: 多处
• duckdb-pivot-unpivot-complete-guide.md: 多处
• duckdb-pivot-unpivot-data-product.md: 多处

CREATE CACHE TABLE（不支持）：

• duckdb-production-enterprise-guide.md: Line 531

CREATE FUNCTION … RETURNS … AS 语法（不支持）：

• duckdb-production-error-handling.md: Line 127
• duckdb-python-udf.md: Line 55, 95, 147, 172, 197, 216, 352

Unsupported: CREATE MACRO with DEFAULT：

• duckdb-sql-advanced-techniques.md: Line 109

Unsupported: partial indexes：

• duckdb-performance-tuning-ultimate-guide.md: Line 262
• duckdb-real-time-streaming-guide.md: Line 266

Unsupported: REINDEX TABLE：

• duckdb-performance-tuning-ultimate-guide.md: Line 276

Unsupported: ALTER TABLE … ORDER BY：

• duckdb-production-deployment-guide.md: Line 474

Unsupported: CREATE MATERIALIZED VIEW：

• duckdb-merge-upsert-incremental-reporting.md: Line 279

Unsupported: Variant cast :: syntax：

• duckdb-upcoming-v2-roadmap-preview.md: Line 34
• duckdb-v154-variegata-key-features.md: Line 46
• duckdb-variant-type.md: Line 275

Unsupported: json_execute_serialized_sql：

• duckdb-security-audit-2026-aug.md: Line 171

Unsupported: FORMAT_DATE：

• duckdb-copy-to-export-complete-guide.md: Line 131

Unsupported: DuckLake 语法：

• ducklake-v1-intro.md: Line 103, 119, 248

Unsupported: -» JSON 操作符：

• duckdb-v15-variegata.md: Line 32

Unsupported: using duckdb in CREATE TABLE：

• pg-duckdb-postgres-analytics.md: Line 216

Shell 命令被当作 SQL 解析：

• duckdb-data-encryption.md: Line 104 — $ hexdump -C ...
• duckdb-online-shell.md: Line 112, 132, 142 — .help, .files list, .pick
• duckdb-vs-sqlite-benchmark.md: Line 150 — .mode csv
• duckdb-quack-core-extension-guide.md: Line 62 — !server

CREATE TABLE 带空格的名字：

• duckdb-list-pivot-mastery.md: Line 129 — CREATE TABLE shopping cart AS

TransactionContext Error（事务中止）：

• duckdb-list-pivot-mastery.md: Line 175, 220, 301
• duckdb-pivot-unpivot-complete-guide.md: Line 28, 55

VALUES 列表长度不一致：

• duckdb-smart-weekly-report-automation.md: Line 49

Invalid Port：

• duckdb-quack-core-extension-guide.md: Line 81

AUTHORIZATION_TYPE oauth2 缺少 secret：

• duckdb-iceberg-features.md: Line 24
• duckdb-iceberg-v153-advanced-features.md: Line 30
• duckdb-iceberg-v153-features.md: Line 32

Iceberg 版本推测禁用：

• duckdb-iceberg-features.md: Line 162
• duckdb-iceberg-v153-advanced-features.md: Line 183
• duckdb-iceberg-v153-features.md: Line 204, 304

Extension 加载错误：

• duckdb-extensionkit-csharp.md: Line 172

Secret Validation Failure：

• duckdb-delta-lake-adhoc-query.md: Line 91

Unsupported: ML model loading（文件不存在）：

• duckdb-ml-inference-infera.md: Line 44, 147

SELECT REPLACE(…) 语法错误：

• duckdb-complete-guide.md: Line 116 — SELECT REPLACE(amount * 1.1 AS amount) FROM sales

LATERAL 子查询语法错误：

• duckdb-lateral-join-unnest.md: Line 220
• duckdb-marketing-attribution-saas.md: Line 155

CROSS JOIN UNNEST 语法错误：

• duckdb-list-functions-complete-guide.md: Line 598

list_aggr 函数参数不匹配：

• duckdb-json-tree-list-operations.md: Line 205

read_ndjson_auto 用作标量函数：

• duckdb-json-tree-list-operations.md: Line 52

IVF_FLAT WITH 语法错误：

• duckdb-lance-vector-search.md: Line 153, 291

USING IVF_FLAT 语法错误：

• duckdb-lance-extension-guide.md: Line 131

Unsupported: RANGE partitioning：

• duckdb-startup-analytics-dashboard.md: Line 325

Unsupported: PRAGMA max_memory = 8GB：

• duckdb-startup-analytics-dashboard.md: Line 353

Unsupported: CREATE DATABASE IF NOT EXISTS：

• duckdb-startup-analytics-dashboard.md: Line 32

Unsupported: QUALIFY with …：

• duckdb-qualify-clause.md: Line 216, 252, 269

Unsupported: FILTER (WHERE …)：

• duckdb-filter-clause.md: Line 310

Invalid named parameter for read_json_auto：

• duckdb-geojson-complete-guide.md: 多处

Named parameter ‘geojson’ not valid：

• duckdb-geojson-complete-guide.md

sqlframe/pyspark 迁移类（部分通过）：

• duckdb-sqlframe-pyspark-migration.md: ✅ PASSED

🔴 严重错误（需立即修复）

1. CREATE DOMAIN — 未发现使用，但需警惕（DuckDB 不支持）
2. Python unterminated string literal — 164 处，涉及约 50 篇文章，需逐个修复
3. WITH WITH … 重复关键字 — 约 40 处，SQL 语法错误
4. temp catalog 命名冲突 — 约 80 处，最普遍的问题

💡 建议

1. 修复 temp catalog 问题：将所有 temp.table_name 引用改为直接在默认 schema 中创建临时表（使用 CREATE TEMP TABLE 或省略 temp. 前缀）

2. 修复 Python 字符串字面量：检查所有标记文章的 Python 代码块，确保三重引号字符串正确闭合，转义字符正确

3. 修复重复 CTE 关键字：将 WITH WITH cte_name AS (...) 修正为 WITH cte_name AS (...)

4. 修正非 DuckDB 语法：

   • LOAD DATA FROM → 使用 COPY ... FROM 或 read_csv_auto
   • CREATE EXTENSION → DuckDB 使用 INSTALL + LOAD
   • CREATE MATERIALIZED VIEW → 使用 DuckDB 物化视图语法
   • SHOW SCHEMAS FROM → 使用 SHOW SCHEMAS
   • INTERVAL rn DAY（变量间隔）→ 使用 INTERVAL '1 day' * rn
   • GROUP BY ... - INTERVAL → 类似处理

5. 将 Shell/CLI 命令标记为 text 而非 sql：.help、.mode csv、duckdb -c 等应使用 ```text 而非 ```sql

6. 将 DBT/Jinja 模板标记为 text 或 sql+jinja：{{ ref(...) }} 和 {{ config(...) }} 不应作为纯 SQL 验证

7. 更新验证脚本：

   • 添加对 temp. catalog 错误的更友好处理（目前全部报错，但部分可能是合理的）
   • 增加对 .. 省略号语法的忽略
   • 增强对多行 Python 代码块中文本引用的处理

8. 重新运行检查：修复后再次运行验证脚本确认所有问题已解决

📈 统计摘要