QueryChat

QueryChat(
    data_source,
    table_name,
    *,
    id=None,
    greeting=None,
    client=None,
    tools=('update', 'query'),
    data_description=None,
    categorical_threshold=20,
    extra_instructions=None,
    prompt_template=None,
)

Create a QueryChat instance for Shiny applications.

QueryChat enables natural language interaction with your data through an LLM-powered chat interface. It can be used in Shiny applications, as a standalone chat client, or in an interactive console.

Examples

Basic Shiny app:

from querychat import QueryChat

qc = QueryChat(my_dataframe, "my_data")
qc.app()

Standalone chat client:

from querychat import QueryChat
import pandas as pd

df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
qc = QueryChat(df, "my_data")

# Get a chat client with all tools
client = qc.client()
response = client.chat("What's the average of column a?")

# Start an interactive console chat
qc.console()

Privacy-focused mode: Only allow dashboard filtering, ensuring the LLM can’t see any raw data.

qc = QueryChat(df, "my_data", tools="update")
qc.app()

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.	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`
tools	`TOOL_GROUPS` \| tuple[`TOOL_GROUPS`, …] \| None	Which querychat tools to include in the chat client by default. Can be: - A single tool string: `"update"` or `"query"` - A tuple of tools: `("update", "query")` - `None` or `()` to disable all tools Default is `("update", "query")` (both tools enabled). Set to `"update"` to prevent the LLM from accessing data values, only allowing dashboard filtering without answering questions. The tools can be overridden per-client by passing a different `tools` parameter to the `.client()` method.	`('update', 'query')`
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
app	Quickly chat with a dataset.
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.
generate_greeting	Generate a welcome greeting for the chat.
server	Initialize Shiny server logic.
sidebar	Create a sidebar containing the querychat UI.
ui	Create the UI for the querychat component.

app

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

QueryChat.cleanup()

Clean up resources associated with the data source.

client

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

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

Launch an interactive console chat with the data.

generate_greeting

QueryChat.generate_greeting(echo='none')

Generate a welcome greeting for the chat.

server

QueryChat.server(data_source=None, enable_bookmarking=False, id=None)

Initialize Shiny server logic.

This method is intended for use in Shiny Code mode, where the user must explicitly call .server() within the Shiny server function. In Shiny Express mode, you can use querychat.express.QueryChat instead of querychat.QueryChat, which calls .server() automatically.

Parameters

Name	Type	Description	Default
data_source	Optional[`IntoFrame` \| `sqlalchemy`.`Engine` \| `ibis`.`Table`]	Optional data source to use. If provided, sets the data_source property before initializing server logic. This is useful for the deferred pattern where data_source is not known at initialization time.	`None`
enable_bookmarking	bool	Whether to enable bookmarking for the querychat module.	`False`
id	Optional[str]	Optional module ID for the QueryChat instance. If not provided, will use the ID provided at initialization. This must match the ID used in the `.ui()` or `.sidebar()` methods.	`None`

Examples

from shiny import App, render, ui
from seaborn import load_dataset
from querychat import QueryChat

titanic = load_dataset("titanic")

qc = QueryChat(titanic, "titanic")


def app_ui(request):
    return ui.page_sidebar(
        qc.sidebar(),
        ui.card(
            ui.card_header(ui.output_text("title")),
            ui.output_data_frame("data_table"),
        ),
        title="Titanic QueryChat App",
        fillable=True,
    )


def server(input, output, session):
    qc_vals = qc.server(enable_bookmarking=True)

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

    @render.text
    def title():
        return qc_vals.title() or "My Data"


app = App(app_ui, server, bookmark_store="url")

Returns

Name	Type	Description
	ServerValues[`IntoFrameT`]	A ServerValues dataclass containing session-specific reactive values and the chat client. See ServerValues documentation for details on the available attributes.

sidebar

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.

ui

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.