# Query data with SQL cells

Use SQL cells to query the following data sources:

* Attached databases

* DataFrames

* Attached `.csv` files

> **Tip:**
> SQL cells are the recommended method of work with SQL when activating [Reactive mode](kernel-management.html).

Procedure: Query a database in an SQL cell

1. Add an SQL cell:

* From Attached data 1. Go to `Tools | Attached data`. 2. Switch to the Databases tab. 3. In the card of the database you want to query, click ![Dots](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/dots.svg)(More) and select Connect SQL cell. ![Opening an SQL cell from Attached data](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/connect_sql.png)

* In the editor: 1. Hover over the bottom border of a cell and select `More | SQL`. If there are several attached databases, in the cell, click Select database and select the required data source. ![Selecting a database for querying](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/attached_db_selection.png)

2. Enter an SQL statement.

> **Note:**
> The cell provides code completion based on the introspected database schema.

3. (Optional) You can also use the following options on the cell toolbar:

* Browse schema: to view the queried database schema, which will be shown in the Attached data tool.

* Limit 500: to set the limit of returned rows to 500.

4. Run the query (by clicking Run or pressing `Ctrl+Enter` (Windows), `^ Return` (macOS)). The result set will be shown in the output and saved to a DataFrame. The resulting DataFrame name is shown in the cell toolbar.

> **Tip:**
> By clicking the Stop button or interrupting/restarting the kernel, you explicitly stop querying the database.

5. (Optional) You may be required to log in to the database you're querying if the connection was created without providing credentials:

* In the authorization request box, click Log in.

* In the Log in to [database_name] dialog, provide a login and a password. Then, click the Authorization button.

6. (Optional) To rename the data object, click the object name next to Result saved to on the SQL toolbar.

> **Tip:**
> To get a visual representation of the retrieved data, switch to the Visualize tab. Find more details in [Use automatic plotting](automatic-plotting.html).

Example 1

The image below shows an SQL cell querying a PostgreSQL database, 500 row limit enabled.

![Querying a PostgreSQL database](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/sql_result.png)

> **Note: OAuth authentication (Google BigQuery or Snowflake)**
> Notebook collaborators may be required to provide their credentials to access the database in an SQL cell if OAuth authentication was used for a connection.
>
> ![Authentication required](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/auth_sql.png)

Procedure: Query a DataFrame or .csv file in an SQL cell

The procedure queries a DataFrame or a .csv file from notebook or workspace files and saves the result set to a DataFrame.

> **Note:**
> To query DataFrames, use the [DuckDB SQL dialect](https://duckdb.org/docs/sql/introduction).

1. Hover over the bottom border of a cell and select `More | SQL`.

2. In the added SQL cell, click Select database and select Dataframes.

3. (Optional) To rename the resulting DataFrame:

1. Click the name next to Result saved to on the SQL cell toolbar.

2. Enter a new name and press `Enter` (Windows), `Return` (macOS).

4. Enter an SQL statement. Run the query. The result set will be shown in the output and saved to a new DataFrame under the name shown on the SQL cell toolbar.

> **Tip:**
> By clicking the Stop button or interrupting/restarting the kernel, you explicitly stop querying the database.

5. (Optional) To get a visual representation of the retrieved data, switch to the Visualize tab. Find more details in [Use automatic plotting](automatic-plotting.html).

Example 2

The image below shows a code cell that generates a DataFrame, and an SQL cell that queries that DataFrame.

![Querying a DataFrame](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/sql_df.png)

Example 3

The image below shows an SQL cell that queries a .csv file stored in Notebook files.

![Querying a csv file](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/sql_csv.png)

Procedure: Query an SQLite database

The procedure describes how to query an SQLite database using an SQL cell.

1. Add an SQLite database to the notebook files. The simplest way is to drag the file into the editor.

2. Open the Attached data tool from the left-hand sidebar of the editor. The respective file will be available in the Notebook files category on the Files tab.

![SQLite table added to notebook files](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/sqlite.png)

3. Right-click the file and select Copy file path.

4. Go back to the editor and add an SQL cell:

1. Hover over the bottom border of a cell.

2. Select `More | SQL`.

5. In the added SQL cell, click Select database and select SQLite.

6. In the Path field, paste the copied path to the added SQLite database file. Instead of the full path, you can just use the file name.

7. (Optional) To rename the resulting DataFrame:

1. Click the name next to Result save to on the SQL cell toolbar.

2. Enter a new name and press `Enter` (Windows), `Return` (macOS).

8. Enter an SQL statement. Run the query. The result set will be shown in the output and saved to a new DataFrame under the name shown on the SQL cell toolbar.

> **Tip:**
> By clicking the Stop button or interrupting/restarting the kernel, you explicitly stop querying the database.

9. (Optional) To get a visual representation of the retrieved data, switch to the Visualize tab. Find more details in [Use automatic plotting](automatic-plotting.html).

Example 4

The image below shows an SQL cell that queries an SQLite database file stored in Notebook files.

![Querying an SQLite database table](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/sqlite_table.png)

Procedure: Create an SQLite table

You can create an SQLite table and save it to an SQLite database. This can be either one of the databases that you already added to the notebook files or a new table that will be created as a result of this procedure.

1. Hover over the bottom border of a cell and select `More | SQL`.

2. In the added SQL cell, click Select database and select SQLite.

3. In the Path field, provide a name for the SQLite database where you want to create this table. If this step is skipped, the table will be added to the `datalore.sqlite` database.

4. (Optional) To rename the resulting DataFrame:

1. Click the name next to Result save to on the SQL cell toolbar.

2. Enter a new name and press `Enter` (Windows), `Return` (macOS).

5. Enter an SQLite statement to create a table. Run the query. The result set will be shown in the output and saved to a new DataFrame under the name shown on the SQL cell toolbar. The table will be added to the database file that you previously specified.

Example 5

The image below shows an SQL cell that creates an SQLite table for an SQLite database file stored in Notebook files and an SQL cell that queries this new table.

![Creating an SQLite table](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/create_sqlite.png)

> **Note:**
> We do not recommend opening SQLite database files for editing as it may result in a malfunction of the database disc image.

## Parameterized SQL queries

You can use Python variables in your SQL queries in Datalore. Such queries can be reused repeatedly with different values, which helps make your reports more interactive.

Supported variable types are: strings, numbers, booleans, and lists. Make sure you place your variable inside `{}` brackets.

Parameterized SQL query example

In the image below, you can see two cells:

* Dropdown interactive control cell using the `method` variable.

* SQL cell where the value in payment column equals the `method` variable value selected from the dropdown list.

![Using a parameterized SQL query](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/parameterized_sql.png)

## Table parametrisation for SQL cells

Datalore allows for table parametrization by supporting unsafe parameters for SQL cell statements. The syntax is as follows:

```SQL
select * from {table_name | unsafe} limit {n}
```

In the code example above, the {table_name | unsafe} part will assume the value of the `table_name` variable.

### String variables for unsafe parameters

To pass a string variable to an unsafe parameter, use quote escaping quotes. See the examples below:

Unsafe parameter defined in a code cell
: ```PYTHON
: product = "'Product'"
: ```

Unsafe parameter referenced in an SQL cell
: ```SQL
: SELECT * from releases
: where jb_product in ({product | unsafe})
: ```

Resulting SQL query
: ```SQL
: SELECT * from releases
: where jb_product in ('Product')
: ```

## Run SQL cells as functions from other cells

Datalore allows you to wrap queries from SQL cells into Python code and use them as functions with parameters. The function with an SQL cell statement has the following syntax: `execute_sql_cell_{DataFrame_name}`, where `{dataframe_name}` is the name of the DataFrame that saves the result of the SQL cell you want to use.

Example

Cell 1, Python

```PYTHON
import pandas as pd
idd = [1,2]
lim = 10
```

Cell 2, SQL (result saved to a `df_1` DataFrame)

```
select * from small_iris_df
where small_iris_df."Id" in {idd}
limit {lim}
```

Cell 3, Python (function using the `df_1` DataFrame from Cell 2)

```PYTHON
frames = [execute_sql_cell_df_1(i,5,2)  for i in range(5) ]
# Number of the function parameters matches the count of values of variables in the SQL statement: idd - 2 values , lim - 1 value.
pd.concat(frames)
```

## Override automatic header detection

The procedure below explains how to override [automatic header detection](https://duckdb.org/docs/data/csv/auto_detection.html).

Consider the example in the image below. The first row contains string values, which is detected as the table header.

![Automatic header in retrieved table](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/with_header.png)

To disable automatic header detection, query the file using the `read_csv` function with the `header` parameter set to `false`. When querying .tsv files, the additional `sep='\t'` is also required.

![Disabling automatic header detection](https://resources.jetbrains.com.cn/help/img/datalore/2026.3/no_header.png)

## Keywords

sql statement, sql query, retrieve data, query table, query database