fetchdf is a DuckDB result-fetching method that converts a query result into a pandas DataFrame. It fits workflows that move between SQL filtering and pandas analysis, while cursors remain lighter for row-by-row iteration. section 6.3
Filter a pandas DataFrame with parameterized SQL
people = pd.DataFrame({"name": ["Michael Hunger", "Michael Simons", "Mark Needham"], "country": ["Germany", "Germany", "Great Britain"]}) params = {"country": "Germany"} result = duckdb.execute(""" SELECT * FROM people WHERE country <> $country """, params).fetchdf() The returned result is a pandas DataFrame ready for further analysis.
Use fetchdf when the next step benefits from pandas or an interactive table:
- Query pandas DataFrames directly as DuckDB relations. section 6.3
- Pass parameterized values into SQL and receive structured tabular results. section 6.3
- Feed query results into Streamlit, where pandas DataFrames render as interactive tables. section 9.1.3
params = {"country": "Germany"}
duckdb.execute("""
SELECT *
FROM people
WHERE country <> $country
""", params).fetchdf()name country
0 Mark Great Britain
Shows the compact Python pattern for parameterized SQL followed by fetchdf. section 6.3
