express.QueryChat

express.QueryChat(
    data_source,
    table_name,
    *,
    id=None,
    greeting=None,
    client=None,
    data_description=None,
    categorical_threshold=20,
    extra_instructions=None,
    prompt_template=None,
    enable_bookmarking='auto',
)

Use QueryChat with Shiny Express.

This class makes it easy to use querychat within Shiny Express apps – it automatically calls .server() during initialization, so you don’t have to do it manually.

Examples

from querychat.express import QueryChat
from seaborn import load_dataset
from shiny.express import app_opts, render, ui

titanic = load_dataset("titanic")

qc = QueryChat(titanic, "titanic")
qc.sidebar()

with ui.card(fill=True):
    with ui.card_header():

        @render.text
        def title():
            return qc.title() or "Titanic Dataset"

    @render.data_frame
    def data_table():
        return qc.df()


ui.page_opts(
    title="Titanic QueryChat App",
    fillable=True,
)

app_opts(bookmark_store="url")

Parameters

Name	Type	Description	Default
data_source	`IntoFrame` \| `sqlalchemy`.`Engine`	Either a Narwhals-compatible data frame (e.g., Polars or Pandas) or a SQLAlchemy engine containing the table to query against.	required
table_name	str	If a data_source is a data frame, a name to use to refer to the table in SQL queries (usually the variable name of the data frame, but it doesn’t have to be). If a data_source is a SQLAlchemy engine, the table_name is the name of the table in the database to query against.	required
id	Optional[str]	An optional ID for the QueryChat module. If not provided, an ID will be generated based on the table_name.	`None`
greeting	Optional[str \| Path]	A string in Markdown format, containing the initial message. If a pathlib.Path object is passed, querychat will read the contents of the path into a string with `.read_text()`. You can use `querychat.greeting()` to help generate a greeting from a querychat configuration. If no greeting is provided, one will be generated at the start of every new conversation.	`None`
client	Optional[str \| `chatlas`.`Chat`]	A `chatlas.Chat` object or a string to be passed to `chatlas.ChatAuto()`’s `provider_model` parameter, describing the provider and model combination to use (e.g. `"openai/gpt-4.1"`, “anthropic/claude-sonnet-4-5”, “google/gemini-2.5-flash”. etc). If `client` is not provided, querychat consults the `QUERYCHAT_CLIENT` environment variable. If that is not set, it defaults to `"openai"`.	`None`
data_description	Optional[str \| Path]	Description of the data in plain text or Markdown. If a pathlib.Path object is passed, querychat will read the contents of the path into a string with `.read_text()`.	`None`
categorical_threshold	int	Threshold for determining if a column is categorical based on number of unique values.	`20`
extra_instructions	Optional[str \| Path]	Additional instructions for the chat model. If a pathlib.Path object is passed, querychat will read the contents of the path into a string with `.read_text()`.	`None`
prompt_template	Optional[str \| Path]	Path to or a string of a custom prompt file. If not provided, the default querychat template will be used. This should be a Markdown file that contains the system prompt template. The mustache template can use the following variables: - `{db_engine}`: The database engine used (e.g., “DuckDB”) - `{schema}`: The schema of the data source, generated by `data_source.get_schema()` - `{data_description}`: The optional data description provided - `{extra_instructions}`: Any additional instructions provided	`None`

Attributes

Name	Description
client	Get the (session-specific) chat client.
data_source	Get the current data source.
system_prompt	Get the system prompt.

Methods

Name	Description
app	Quickly chat with a dataset.
cleanup	Clean up resources associated with the data source.
df	Reactively read the current filtered data frame that is in effect.
generate_greeting	Generate a welcome greeting for the chat.
sidebar	Create a sidebar containing the querychat UI.
sql	Reactively read (or set) the current SQL query that is in effect.
title	Reactively read (or set) the current title that is in effect.
ui	Create the UI for the querychat component.

app

express.QueryChat.app(bookmark_store='url')

Quickly chat with a dataset.

Creates a Shiny app with a chat sidebar and data table view – providing a quick-and-easy way to start chatting with your data.

Parameters

Name	Type	Description	Default
bookmark_store	Literal['url', 'server', 'disable']	The bookmarking store to use for the Shiny app. Options are: - `"url"`: Store bookmarks in the URL (default). - `"server"`: Store bookmarks on the server. - `"disable"`: Disable bookmarking.	`'url'`

Returns

Name	Type	Description
	`App`	A Shiny App object that can be run with `app.run()` or served with `shiny run`.

cleanup

express.QueryChat.cleanup()

Clean up resources associated with the data source.

Call this method when you are done using the QueryChat object to close database connections and avoid resource leaks.

Returns

Name	Type	Description
	None

df

express.QueryChat.df()

Reactively read the current filtered data frame that is in effect.

Returns

Name	Type	Description
	`pd`.`DataFrame`	The current filtered data frame as a pandas DataFrame. If no query has been set, this will return the unfiltered data frame from the data source.

generate_greeting

express.QueryChat.generate_greeting(echo='none')

Generate a welcome greeting for the chat.

By default, QueryChat() generates a greeting at the start of every new conversation, which is convenient for getting started and development, but also might add unnecessary latency and cost. Use this method to generate a greeting once and save it for reuse.

Parameters

Name	Type	Description	Default
echo	Literal['none', 'output']	If `echo = "output"`, prints the greeting to standard output. If `echo = "none"` (default), does not print anything.	`'none'`

Returns

Name	Type	Description
		The greeting string (in Markdown format).

sidebar

express.QueryChat.sidebar(width=400, height='100%', fillable=True, **kwargs)

Create a sidebar containing the querychat UI.

Parameters

Name	Type	Description	Default
width	int	Width of the sidebar in pixels.	`400`
height	str	Height of the sidebar.	`'100%'`
fillable	bool	Whether the sidebar should be fillable. Default is `True`.	`True`
**kwargs		Additional arguments passed to `shiny.ui.sidebar()`.	`{}`

Returns

Name	Type	Description
	ui.`Sidebar`	A sidebar UI component.

sql

express.QueryChat.sql(query=None)

Reactively read (or set) the current SQL query that is in effect.

Parameters

Name	Type	Description	Default
query	Optional[str]	If provided, sets the current SQL query to this value.	`None`

Returns

Name	Type	Description
	str \| None \| bool	If no `query` is provided, returns the current SQL query as a string (or `None` if no query has been set). If a `query` is provided, returns `True` if the query was changed to a new value, or `False` if it was the same as the current value.

title

express.QueryChat.title(value=None)

Reactively read (or set) the current title that is in effect.

The title is a short description of the current query that the LLM provides to us whenever it generates a new SQL query. It can be used as a status string for the data dashboard.

Parameters

Name	Type	Description	Default
value	Optional[str]	If provided, sets the current title to this value.	`None`

Returns

Name	Type	Description
	str \| None \| bool	If no `value` is provided, returns the current title as a string, or `None` if no title has been set due to no SQL query being set. If a `value` is provided, sets the current title to this value and returns `True` if the title was changed to a new value, or `False` if it was the same as the current value.

ui

express.QueryChat.ui(**kwargs)

Create the UI for the querychat component.

Parameters

Name	Type	Description	Default
**kwargs		Additional arguments to pass to `shinychat.chat_ui()`.	`{}`

Returns

Name	Type	Description
		A UI component.