跳到主要内容

Troubleshooting

故障排查​

运行 EXPLAIN 显示换行符​

在 Python 中，EXPLAIN 语句的输出会包含硬换行符（\n）：

In [1]: import goose
   ...: goose.sql("EXPLAIN SELECT 42 AS x")
Out[1]:
┌───────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│  explain_key  │                                                   explain_value                                                   │
│    varchar    │                                                      varchar                                                      │
├───────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ physical_plan │ ┌───────────────────────────┐\n│         PROJECTION        │\n│   ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   │\n│             x   …  │
└───────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

可通过 print explain() 函数的输出进行规避：

In [2]: print(goose.sql("SELECT 42 AS x").explain())
Out[2]:
┌───────────────────────────┐
│         PROJECTION        │
│   ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   │
│             x             │
└─────────────┬─────────────┘
┌─────────────┴─────────────┐
│         DUMMY_SCAN        │
└───────────────────────────┘

另请参阅 Jupyter 指南，了解在 Jupyter 中使用 JupySQL 的技巧。

Windows 上的崩溃与错误​

在 Windows 上导入 Goose 时，Python 运行时可能在导入阶段或首次使用时崩溃或报错：

import goose

goose.sql("...")
ImportError: DLL load failed while importing goose: The specified module could not be found.
Windows fatal exception: access violation

Current thread 0x0000311c (most recent call first):
  File "<stdin>", line 1 in <module>
Process finished with exit code -1073741819 (0xC0000005)

该问题通常由过旧的 Microsoft Visual C++（MSVC）Redistributable 运行库引起。 解决方法是安装最新的 MSVC Redistributable 包。 或者，你也可以让 pip 从源码编译安装该包：

python3 -m pip install goose --no-binary goose

Relational API 中的参数化查询​

向 sql()、query() 或 from_query() 传入查询参数会带来明显性能开销。 目前 core 中还没有支持预处理语句的 relation 类型，因此参数化查询会立即物化为中间表示。与非参数化路径相比，这会导致至少 5 倍的处理开销和接近 2 倍的内存使用。

建议改用 execute() 执行参数化查询，再通过 replacement scan 将结果接入 relational API：

import goose

conn = goose.connect()

# Use execute() for the parameterized query
df = conn.execute("SELECT * FROM my_table WHERE x = ?", [42]).df()

# Use a replacement scan to continue with the relational API
conn.sql("SELECT * FROM df WHERE y > 0").order("y").show()

已知问题​

很遗憾，有些问题要么超出我们的控制范围，要么非常隐蔽、难以定位。 下面列出了一些你可能需要关注的问题，具体取决于你的工作流。

Numpy 导入与多线程​

当使用多线程并将结果直接获取为 Numpy 数组，或间接通过 Pandas DataFrame 获取时，可能需要确保 numpy.core.multiarray 已被导入。 如果该模块未在主线程中导入，而是在执行过程中由其他线程尝试导入，可能会导致死锁或崩溃。

为避免该问题，建议在启动线程前先执行 import numpy.core.multiarray。

在 Jupyter 中 DESCRIBE 和 SUMMARIZE 返回空表​

DESCRIBE 和 SUMMARIZE 语句会返回空表：

%sql
CREATE OR REPLACE TABLE tbl AS (SELECT 42 AS x);
DESCRIBE tbl;

可通过将其包裹到子查询中来规避：

%sql
CREATE OR REPLACE TABLE tbl AS (SELECT 42 AS x);
FROM (DESCRIBE tbl);

IPython 中 JupySQL 的 Protobuf 错误​

在 IPython 中加载 JupySQL 扩展会失败：

In [1]: %load_ext sql
ImportError: cannot import name 'builder' from 'google.protobuf.internal' (unknown location)

解决方法是修复 protobuf 包。这可能需要卸载冲突的包，例如：

%pip uninstall tensorflow
%pip install protobuf