QueryChat

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

Create a QueryChat instance.

Examples

from querychat import QueryChat

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

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
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.
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.

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

Returns

Name	Type	Description
	None

generate_greeting

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).

server

QueryChat.server(enable_bookmarking=False)

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
enable_bookmarking	bool	Whether to enable bookmarking for the querychat module.	False

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	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, **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.

ui

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.