{"id":6845,"library":"qpd","title":"qpd: Query Pandas Using SQL","description":"QPD (Query Pandas Dataframes) is a Python library that allows users to run SQL `SELECT` statements on pandas-like dataframes, including Pandas, Dask, and Ray (via Modin on Ray). It translates SQL directly into dataframe operations, prioritizing correctness and consistent behavior across backends, even handling SQL-specific behaviors like `GROUP BY` with null keys differently than default pandas. The current version is 0.4.4. The library has a sporadic but active release cadence, with multiple minor updates in recent history, primarily focusing on compatibility and bug fixes.","status":"active","version":"0.4.4","language":"en","source_language":"en","source_url":"http://github.com/goodwanghan/qpd","tags":["pandas","sql","dataframe","dask","ray","fugue"],"install":[{"cmd":"pip install qpd","lang":"bash","label":"Base installation"},{"cmd":"pip install qpd[all]","lang":"bash","label":"Installation with Dask and Ray dependencies"}],"dependencies":[{"reason":"Core dataframe backend.","package":"pandas","optional":false},{"reason":"Optional backend for Dask DataFrames.","package":"dask","optional":true},{"reason":"Optional backend for Ray DataFrames (via Modin on Ray).","package":"ray","optional":true}],"imports":[{"note":"Main function for running SQL on Pandas DataFrames.","symbol":"run_sql_on_pandas","correct":"from qpd_pandas import run_sql_on_pandas"}],"quickstart":{"code":"import pandas as pd\nfrom qpd_pandas import run_sql_on_pandas\n\n# Create a sample Pandas DataFrame\ndata = {\n    'id': [1, 2, 3, 4, 5, 6, 7, 8],\n    'name': ['Alice', 'Bob', 'Charlie', 'David', 'Eve', 'Frank', 'Grace', 'Heidi'],\n    'age': [25, 30, 35, 25, 40, 30, 35, 25],\n    'city': ['New York', 'London', 'Paris', 'London', 'New York', 'Paris', 'London', 'New York']\n}\ndf = pd.DataFrame(data)\n\n# Define an SQL query\nsql_query = \"\"\"\n    SELECT city, AVG(age) AS avg_age, COUNT(id) AS num_people\n    FROM df\n    WHERE age > 25\n    GROUP BY city\n    HAVING COUNT(id) > 1\n    ORDER BY avg_age DESC\n\"\"\"\n\n# Run the SQL query on the DataFrame\nresult_df = run_sql_on_pandas(sql_query, df=df)\n\nprint(result_df)","lang":"python","description":"This quickstart demonstrates how to use `qpd` to execute a SQL `SELECT` query on a Pandas DataFrame. It creates a sample DataFrame, defines a SQL query with `WHERE`, `GROUP BY`, `HAVING`, and `ORDER BY` clauses, and then uses `run_sql_on_pandas` to get the resulting DataFrame."},"warnings":[{"fix":"Be mindful of `NULL` handling in group keys. If specific Pandas-like null dropping behavior is desired, preprocess the DataFrame before passing it to `qpd` or post-process the `qpd` result.","message":"QPD's SQL implementation for `GROUP BY` follows SQL standards, where `NULL` keys are treated as a distinct group. This differs from default Pandas `groupby()` behavior which often drops `NULL` keys by default. Users should be aware of this semantic difference when migrating SQL queries or expecting Pandas-like output for null values in grouping columns.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `qpd` to version 0.4.1 or higher when using Pandas 2.x or newer: `pip install qpd>=0.4.1`.","message":"QPD versions prior to 0.4.1 might have compatibility issues with Pandas 2.x. Version 0.4.1 introduced explicit compatibility for Pandas 2.","severity":"breaking","affected_versions":"<0.4.1"},{"fix":"Upgrade `qpd` to version 0.2.4 or higher to avoid unintended side effects on input DataFrames: `pip install qpd>=0.2.4`.","message":"In `qpd` versions 0.2.3 and older, certain set operations could unexpectedly alter the input DataFrame by adding columns. This bug was fixed in version 0.2.4.","severity":"gotcha","affected_versions":"<=0.2.3"},{"fix":"Restrict SQL usage to `SELECT` statements for dataframe querying. For data modification or schema changes, use the native DataFrame API (Pandas, Dask, Ray).","message":"QPD currently focuses primarily on `SELECT` statements in SQL. Support for other SQL DDL/DML operations (e.g., `INSERT`, `UPDATE`, `DELETE`, `CREATE TABLE`) is not explicitly provided or may be limited.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}