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.
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.
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.
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".
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.
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().
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().
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
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.
This method creates a standalone chat client configured with the specified tools and callbacks. Each call returns an independent client instance with its own conversation state.
Which tools to include: "update", "query", or both. Can be: - A single tool string: "update" or "query" - A tuple of tools: ("update", "query") - None or () to skip adding any tools - If not provided (default), uses the tools specified during initialization
Optional callback function to call when the update_dashboard tool succeeds. Takes a dict with "query" and "title" keys. Only used if "update" is in tools.
This method provides a REPL (Read-Eval-Print Loop) interface for chatting with your data from the command line. The console session persists by default, so you can exit and return to continue your conversation.
Which tools to include: “update”, “query”, or both. Can be: - A single tool string: "update" or "query" - A tuple of tools: ("update", "query") - None or () to skip adding any tools - If not provided (default), defaults to ("query",) only for privacy (prevents the LLM from accessing data values) Ignored if new=False and a console session already exists.
'query'
**kwargs
Additional arguments passed to the client() method when creating a new client.
{}
Examples
from querychat import QueryChatimport pandas as pddf = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})qc = QueryChat(df, "my_data")# Start console (query tool only by default)qc.console()# Start fresh console with all tools (using tuple)qc.console(new=True, tools=("update", "query"))# Start fresh console with all tools (using single string for one tool)qc.console(new=True, tools="query")# Continue previous console sessionqc.console() # picks up where you left off
df
express.QueryChat.df()
Reactively read the current filtered data frame that is in effect.
Returns
Name
Type
Description
nw.DataFrame
The current filtered data frame as a narwhals 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.
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.
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.