문제 해결
문제 해결 (Troubleshooting)
Python 클라이언트에서 발생할 수 있는 문제와 알려진 이슈, 그리고 그 해결 방법을 정리했어요.
출처: 문서
본문
문제 해결 (Troubleshooting)
EXPLAIN 실행 시 줄바꿈이 렌더링되는 문제 (Running EXPLAIN Renders Newlines)
Python에서 EXPLAIN 문의 출력에는 하드 줄바꿈(\n)이 포함돼요.
In [1]: import duckdb
...: duckdb.sql("EXPLAIN SELECT 42 AS x")
Out[1]:
┌───────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ explain_key │ explain_value │
│ varchar │ varchar │
├───────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ physical_plan │ ┌───────────────────────────┐\n│ PROJECTION │\n│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │\n│ x … │
└───────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
이것을 해결하려면 explain() 함수의 출력을 print해요.
In [2]: print(duckdb.sql("SELECT 42 AS x").explain())
Out[2]:
┌───────────────────────────┐
│ PROJECTION │
│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│ x │
└─────────────┬─────────────┘
┌─────────────┴─────────────┐
│ DUMMY_SCAN │
└───────────────────────────┘
JupySQL과 함께 Jupyter를 사용하는 팁은 Jupyter 가이드도 확인해 보세요.
Windows에서의 크래시와 오류 (Crashes and Errors on Windows)
Windows에서 DuckDB를 import하면 import 시점이나 첫 사용 시 Python 런타임이 크래시하거나 오류를 반환할 수 있어요.
import duckdb
duckdb.sql("...")
ImportError: DLL load failed while importing duckdb: 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 duckdb --no-binary duckdb
Relational API의 매개변수화 쿼리 (Parameterized Queries in Relational API)
쿼리 파라미터를 sql(), query(), 또는 from_query() 메서드에 전달하는 것은 상당한 성능 오버헤드가 있어요. 현재 core에는 준비문(prepared statements)을 지원하는 relation 타입이 없어서, 매개변수화 쿼리는 즉시 중간 표현으로 구체화돼요. 이 때문에 매개변수화되지 않은 경로에 비해 처리 오버헤드가 최소 5배, 메모리 사용량이 거의 2배가 돼요.
대신 매개변수화 쿼리에는 execute()를 사용하고, 그 결과를 replacement scan을 통해 relational API로 전달해요.
import duckdb
conn = duckdb.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()
알려진 문제 (Known Issues)
안타깝게도 우리의 통제 밖이거나 매우 애매해서/추적하기 어려운 문제가 몇 가지 있어요. 워크플로우에 따라 알아야 할 수 있는 문제 목록은 다음과 같아요.
Numpy Import 멀티스레딩 (Numpy Import Multithreading)
멀티스레딩을 사용하면서 결과를 Numpy 배열로 직접 또는 Pandas DataFrame을 통해 간접적으로 가져올 때, numpy.core.multiarray가 import되도록 보장해야 할 수 있어요. 이 모듈이 메인 스레드에서 import되지 않았고, 실행 중 다른 스레드가 import하려고 하면 교착 상태(deadlock)나 크래시가 발생해요.
이를 피하려면 스레드를 시작하기 전에 import numpy.core.multiarray 하는 것을 권장해요.
DESCRIBE와 SUMMARIZE가 Jupyter에서 빈 테이블 반환 (DESCRIBE and SUMMARIZE Return Empty Tables in Jupyter)
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 오류 (Protobuf Error for JupySQL in IPython)
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