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` \| `ibis`.`Table` \| None	Either a Narwhals-compatible data frame (e.g., Polars or Pandas) or a SQLAlchemy engine containing the table to query against. Can be `None` for deferred binding (set via the `data_source` property before the real session starts).	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
data_source	Get the current data source.
system_prompt	Get the system prompt.

Methods

Name	Description
cleanup	Clean up resources associated with the data source.
client	Create a chat client with registered tools.
console	Launch an interactive console chat with the data.
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.

cleanup

express.QueryChat.cleanup()

Clean up resources associated with the data source.

client

express.QueryChat.client(
    tools=MISSING,
    update_dashboard=None,
    reset_dashboard=None,
)

Create a chat client with registered tools.

Parameters

Name	Type	Description	Default
tools	`TOOL_GROUPS` \| tuple[`TOOL_GROUPS`, …] \| None \| `MISSING_TYPE`	Which tools to include: `"update"`, `"query"`, or both.	`MISSING`
update_dashboard	Callable[[`UpdateDashboardData`], None] \| None	Callback when update_dashboard tool succeeds.	`None`
reset_dashboard	Callable[[], None] \| None	Callback when reset_dashboard tool is invoked.	`None`

Returns

Name	Type	Description
	`chatlas`.`Chat`	A configured chat client.

console

express.QueryChat.console(new=False, tools='query', **kwargs)

Launch an interactive console chat with the data.

df

express.QueryChat.df()

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

Returns

Name	Type	Description
	`IntoFrameT`	The current filtered data frame, in the same format as the original data source (e.g., polars DataFrame, Polars LazyFrame, Ibis Table). If no query has been set, returns the unfiltered data from the data source.

generate_greeting

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

Generate a welcome greeting for the chat.

sidebar

express.QueryChat.sidebar(
    width=400,
    height='100%',
    fillable=True,
    id=None,
    **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`
id	Optional[str]	Optional ID for the QueryChat instance. If not provided, will use the ID provided at initialization.	`None`
**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(id=None, **kwargs)

Create the UI for the querychat component.

Parameters

Name	Type	Description	Default
id	Optional[str]	Optional ID for the QueryChat instance. If not provided, will use the ID provided at initialization.	`None`
**kwargs		Additional arguments to pass to `shinychat.chat_ui()`.	`{}`

Returns

Name	Type	Description
		A UI component.