Title:	Filter and Query Data Frames in 'shiny' Using an LLM Chat Interface
Version:	0.2.0
Description:	Adds an LLM-powered chatbot to your 'shiny' app, that can turn your users' natural language questions into SQL queries that run against your data, and return the result as a reactive data frame. Use it to drive reactive calculations, visualizations, downloads, and more.
License:	MIT + file LICENSE
URL:	https://posit-dev.github.io/querychat/r/, https://posit-dev.github.io/querychat/, https://github.com/posit-dev/querychat
BugReports:	https://github.com/posit-dev/querychat/issues
Depends:	R (≥ 4.1.0)
Imports:	bslib, cli, DBI, ellmer (≥ 0.3.0), htmltools, lifecycle, promises, R6, rlang (≥ 1.1.0), S7, shiny, shinychat (≥ 0.3.0), utils, whisker
Suggests:	bsicons, dbplyr, dplyr, DT, duckdb, knitr, palmerpenguins, rmarkdown, RSQLite, shinytest2, testthat (≥ 3.0.0), withr
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-01-08 21:27:00 UTC; garrick
Author:	Garrick Aden-Buie [aut, cre], Joe Cheng [aut, ccp], Carson Sievert [aut], Posit Software, PBC [cph, fnd]
Maintainer:	Garrick Aden-Buie <garrick@posit.co>
Repository:	CRAN
Date/Publication:	2026-01-12 19:50:02 UTC

querychat: Chat with Your Data Using Natural Language

Description

querychat provides an interactive chat interface for querying data using natural language. It translates your questions into SQL queries, executes them against your data, and displays the results. The package works with both data frames and database connections.

Quick Start

The easiest way to get started is with the QueryChat R6 class:

library(querychat)

# Create a QueryChat object (table name inferred from variable)
qc <- QueryChat$new(mtcars)

# Option 1: Run a complete app with sensible defaults
qc$app()

# Option 2: Build a custom Shiny app
ui <- page_sidebar(
  qc$sidebar(),
  dataTableOutput("data")
)

server <- function(input, output, session) {
  qc$server()
  output$data <- renderDataTable(qc$df())
}

shinyApp(ui, server)

Key Features

• Natural language queries: Ask questions in plain English

• SQL transparency: See the generated SQL queries

• Multiple data sources: Works with data frames and database connections

• Customizable: Add data descriptions, extra instructions, and custom greetings

• LLM agnostic: Works with OpenAI, Anthropic, Google, and other providers via ellmer

Main Components

• QueryChat: The main R6 class for creating chat interfaces

• DataSource, DataFrameSource, DBISource: R6 classes for data sources

Examples

To see examples included with the package, run:

shiny::runExample(package = "querychat")

This provides a list of available examples. To run a specific example, like '01-hello-app', use:

shiny::runExample("01-hello-app", package = "querychat")

Author(s)

Maintainer: Garrick Aden-Buie garrick@posit.co (ORCID)

Authors:

• Joe Cheng joe@posit.co [conceptor]

• Carson Sievert carson@posit.co (ORCID)

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://posit-dev.github.io/querychat/r/

• https://posit-dev.github.io/querychat/

• https://github.com/posit-dev/querychat

• Report bugs at https://github.com/posit-dev/querychat/issues

DBI Source

Description

DBI Source

DBI Source

Details

A DataSource implementation for DBI database connections (SQLite, PostgreSQL, MySQL, etc.). This class wraps a DBI connection and provides SQL query execution against a single table in the database.

Super class

querychat::DataSource -> DBISource

Methods

Public methods

• DBISource$new()

• DBISource$get_db_type()

• DBISource$get_schema()

• DBISource$execute_query()

• DBISource$test_query()

• DBISource$get_data()

• DBISource$cleanup()

• DBISource$clone()

Method new()

Create a new DBISource

Usage

DBISource$new(conn, table_name)

Arguments

Returns

A new DBISource object

Method get_db_type()

Get the database type

Usage

DBISource$get_db_type()

Returns

A string identifying the database type

Method get_schema()

Get schema information for the database table

Usage

DBISource$get_schema(categorical_threshold = 20)

Arguments

Returns

A string describing the schema

Method execute_query()

Execute a SQL query

Usage

DBISource$execute_query(query)

Arguments

Returns

A data frame with query results

Method test_query()

Test a SQL query by fetching only one row

Usage

DBISource$test_query(query, require_all_columns = FALSE)

Arguments

Returns

A data frame with one row of results

Method get_data()

Get all data from the table

Usage

DBISource$get_data()

Returns

A data frame containing all data

Method cleanup()

Disconnect from the database

Usage

DBISource$cleanup()

Returns

NULL (invisibly)

Method clone()

The objects of this class are cloneable with this method.

Usage

DBISource$clone(deep = FALSE)

Arguments

Examples

# Connect to a database
con <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
DBI::dbWriteTable(con, "mtcars", mtcars)

# Create a DBI source
db_source <- DBISource$new(con, "mtcars")

# Get database type
db_source$get_db_type()  # Returns "SQLite"

# Execute a query
result <- db_source$execute_query("SELECT * FROM mtcars WHERE mpg > 25")

# Note: cleanup() will disconnect the connection
# If you want to keep the connection open, don't call cleanup()
db_source$cleanup()

Data Frame Source

Description

A DataSource implementation that wraps a data frame using DuckDB or SQLite for SQL query execution.

Details

This class creates an in-memory database connection and registers the provided data frame as a table. All SQL queries are executed against this database table. See DBISource for the full description of available methods.

By default, DataFrameSource uses the first available engine from duckdb (checked first) or RSQLite. You can explicitly set the engine parameter to choose between "duckdb" or "sqlite", or set the global option querychat.DataFrameSource.engine to choose the default engine for all DataFrameSource instances. At least one of these packages must be installed.

Super classes

querychat::DataSource -> querychat::DBISource -> DataFrameSource

Methods

Public methods

• DataFrameSource$new()

• DataFrameSource$clone()

Method new()

Create a new DataFrameSource

Usage

DataFrameSource$new(
  df,
  table_name,
  engine = getOption("querychat.DataFrameSource.engine", NULL)
)

Arguments

Returns

A new DataFrameSource object

Method clone()

The objects of this class are cloneable with this method.

Usage

DataFrameSource$clone(deep = FALSE)

Arguments

Examples

# Create a data frame source (uses first available: duckdb or sqlite)
df_source <- DataFrameSource$new(mtcars, "mtcars")

# Get database type
df_source$get_db_type()  # Returns "DuckDB" or "SQLite"

# Execute a query
result <- df_source$execute_query("SELECT * FROM mtcars WHERE mpg > 25")

# Explicitly choose an engine
df_sqlite <- DataFrameSource$new(mtcars, "mtcars", engine = "sqlite")

# Clean up when done
df_source$cleanup()
df_sqlite$cleanup()

Data Source Base Class

Description

An abstract R6 class defining the interface that custom QueryChat data sources must implement. This class should not be instantiated directly; instead, use one of its concrete implementations like DataFrameSource or DBISource.

Public fields

Methods

Public methods

• DataSource$get_db_type()

• DataSource$get_schema()

• DataSource$execute_query()

• DataSource$test_query()

• DataSource$get_data()

• DataSource$cleanup()

• DataSource$clone()

Method get_db_type()

Get the database type

Usage

DataSource$get_db_type()

Returns

A string describing the database type (e.g., "DuckDB", "SQLite")

Method get_schema()

Get schema information about the table

Usage

DataSource$get_schema(categorical_threshold = 20)

Arguments

Returns

A string containing schema information formatted for LLM prompts

Method execute_query()

Execute a SQL query and return results

Usage

DataSource$execute_query(query)

Arguments

Returns

A data frame containing query results

Method test_query()

Test a SQL query by fetching only one row

Usage

DataSource$test_query(query, require_all_columns = FALSE)

Arguments

Returns

A data frame containing one row of results (or empty if no matches)

Method get_data()

Get the unfiltered data as a data frame

Usage

DataSource$get_data()

Returns

A data frame containing all data from the table

Method cleanup()

Clean up resources (close connections, etc.)

Usage

DataSource$cleanup()

Returns

NULL (invisibly)

Method clone()

The objects of this class are cloneable with this method.

Usage

DataSource$clone(deep = FALSE)

Arguments

Examples

MyDataSource <- R6::R6Class(
  "MyDataSource",
  inherit = DataSource,
  public = list(
    initialize = function(table_name) {
      self$table_name <- table_name
    }
    # Implement abstract methods here...
  )
)

QueryChat: Interactive Data Querying with Natural Language

Description

QueryChat is an R6 class built on Shiny, shinychat, and ellmer to enable interactive querying of data using natural language. It leverages large language models (LLMs) to translate user questions into SQL queries, execute them against a data source (data frame or database), and various ways of accessing/displaying the results.

The QueryChat class takes your data (a data frame or database connection) as input and provides methods to:

• Generate a chat UI for natural language queries (e.g., ⁠$app()⁠, ⁠$sidebar()⁠)

• Initialize server logic that returns session-specific reactive values (via ⁠$server()⁠)

• Access reactive data, SQL queries, and titles through the returned server values

Usage in Shiny Apps

library(querychat)

# Create a QueryChat object
qc <- QueryChat$new(mtcars)

# Quick start: run a complete app
qc$app()

# Or build a custom Shiny app
ui <- page_sidebar(
  qc$sidebar(),
  verbatimTextOutput("sql"),
  dataTableOutput("data")
)

server <- function(input, output, session) {
  qc_vals <- qc$server()

  output$sql <- renderText(qc_vals$sql())
  output$data <- renderDataTable(qc_vals$df())
}

shinyApp(ui, server)

Public fields

Active bindings

Methods

Public methods

• QueryChat$new()

• QueryChat$client()

• QueryChat$console()

• QueryChat$app()

• QueryChat$app_obj()

• QueryChat$sidebar()

• QueryChat$ui()

• QueryChat$server()

• QueryChat$generate_greeting()

• QueryChat$cleanup()

• QueryChat$clone()

Method new()

Create a new QueryChat object.

Usage

QueryChat$new(
  data_source,
  table_name = missing_arg(),
  ...,
  id = NULL,
  greeting = NULL,
  client = NULL,
  tools = c("update", "query"),
  data_description = NULL,
  categorical_threshold = 20,
  extra_instructions = NULL,
  prompt_template = NULL,
  cleanup = NA
)

Arguments

Returns

A new QueryChat object.

Method client()

Create a chat client, complete with registered tools, for the current data source.

Usage

QueryChat$client(
  tools = NA,
  update_dashboard = function(query, title) {
 },
  reset_dashboard = function() {
 }
)

Arguments

Method console()

Launch a console-based chat interface with the data source.

Usage

QueryChat$console(new = FALSE, ..., tools = "query")

Arguments

Method app()

Create and run a Shiny gadget for chatting with data

Runs a Shiny gadget (designed for interactive use) that provides a complete interface for chatting with your data using natural language. If you're looking to deploy this app or run it through some other means, see ⁠$app_obj()⁠.

library(querychat)

qc <- QueryChat$new(mtcars)
qc$app()

Usage

QueryChat$app(..., bookmark_store = "url")

Arguments

Returns

Invisibly returns a list of session-specific values:

• df: The final filtered data frame

• sql: The final SQL query string

• title: The final title

• client: The session-specific chat client instance

Method app_obj()

A streamlined Shiny app for chatting with data

Creates a Shiny app designed for chatting with data, with:

• A sidebar containing the chat interface

• A card displaying the current SQL query

• A card displaying the filtered data table

• A reset button to clear the query

library(querychat)

qc <- QueryChat$new(mtcars)
app <- qc$app_obj()
shiny::runApp(app)

Usage

QueryChat$app_obj(..., bookmark_store = "url")

Arguments

Returns

A Shiny app object that can be run with shiny::runApp().

Method sidebar()

Create a sidebar containing the querychat UI.

This method generates a bslib::sidebar() component containing the chat interface, suitable for use with bslib::page_sidebar() or similar layouts.

qc <- QueryChat$new(mtcars)

ui <- page_sidebar(
  qc$sidebar(),
  # Main content here
)

Usage

QueryChat$sidebar(
  ...,
  width = 400,
  height = "100%",
  fillable = TRUE,
  id = NULL
)

Arguments

Returns

A bslib::sidebar() UI component.

Method ui()

Create the UI for the querychat chat interface.

This method generates the chat UI component. Typically you'll use ⁠$sidebar()⁠ instead, which wraps this in a sidebar layout.

qc <- QueryChat$new(mtcars)

ui <- fluidPage(
  qc$ui()
)

Usage

QueryChat$ui(..., id = NULL)

Arguments

Returns

A UI component containing the chat interface.

Method server()

Initialize the querychat server logic.

This method must be called within a Shiny server function. It sets up the reactive logic for the chat interface and returns session-specific reactive values.

qc <- QueryChat$new(mtcars)

server <- function(input, output, session) {
  qc_vals <- qc$server(enable_bookmarking = TRUE)

  output$data <- renderDataTable(qc_vals$df())
  output$query <- renderText(qc_vals$sql())
  output$title <- renderText(qc_vals$title() %||% "No Query")
}

Usage

QueryChat$server(
  enable_bookmarking = FALSE,
  ...,
  id = NULL,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Returns

A list containing session-specific reactive values and the chat client with the following elements:

• df: Reactive expression returning the current filtered data frame

• sql: Reactive value for the current SQL query string

• title: Reactive value for the current title

• client: The session-specific chat client instance

Method generate_greeting()

Generate a welcome greeting for the chat.

By default, QueryChat$new() 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.

# Create QueryChat object
qc <- QueryChat$new(mtcars)

# Generate a greeting and save it
greeting <- qc$generate_greeting()
writeLines(greeting, "mtcars_greeting.md")

# Later, use the saved greeting
qc2 <- QueryChat$new(mtcars, greeting = "mtcars_greeting.md")

Usage

QueryChat$generate_greeting(echo = c("none", "output"))

Arguments

Returns

The greeting string in Markdown format.

Method cleanup()

Clean up resources associated with the data source.

This method releases any resources (e.g., database connections) associated with the data source. Call this when you are done using the QueryChat object to avoid resource leaks.

Note: If auto_cleanup was set to TRUE in the constructor, this will be called automatically when the Shiny app stops.

Usage

QueryChat$cleanup()

Returns

Invisibly returns NULL. Resources are cleaned up internally.

Method clone()

The objects of this class are cloneable with this method.

Usage

QueryChat$clone(deep = FALSE)

Arguments

Examples

# Basic usage with a data frame
qc <- QueryChat$new(mtcars)
## Not run: 
app <- qc$app()

## End(Not run)

# With a custom greeting
greeting <- "Welcome! Ask me about the mtcars dataset."
qc <- QueryChat$new(mtcars, greeting = greeting)

# With a specific LLM provider
qc <- QueryChat$new(mtcars, client = "anthropic/claude-sonnet-4-5")

# Generate a greeting for reuse (requires internet/API access)
## Not run: 
qc <- QueryChat$new(mtcars)
greeting <- qc$generate_greeting(echo = "text")
# Save greeting for next time
writeLines(greeting, "mtcars_greeting.md")

## End(Not run)

# Or specify greeting and additional options at initialization
qc <- QueryChat$new(
  mtcars,
  greeting = "Welcome to the mtcars explorer!",
  client = "openai/gpt-4o",
  data_description = "Motor Trend car road tests dataset"
)


# Create a QueryChat object from a database connection
# 1. Set up the database connection
con <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")

# 2. (For this demo) Create a table in the database
DBI::dbWriteTable(con, "mtcars", mtcars)

# 3. Pass the connection and table name to `QueryChat`
qc <- QueryChat$new(con, "mtcars")

Data Source: SQL Tibble

Description

A DataSource implementation for lazy SQL tibbles connected to databases via dbplyr::tbl_sql() or dplyr::sql().

Super classes

querychat::DataSource -> querychat::DBISource -> TblSqlSource

Public fields

Methods

Public methods

• TblSqlSource$new()

• TblSqlSource$get_db_type()

• TblSqlSource$get_schema()

• TblSqlSource$execute_query()

• TblSqlSource$test_query()

• TblSqlSource$prep_query()

• TblSqlSource$get_data()

• TblSqlSource$cleanup()

• TblSqlSource$clone()

Method new()

Create a new TblSqlSource

Usage

TblSqlSource$new(tbl, table_name = missing_arg())

Arguments

Returns

A new TblSqlSource object

Method get_db_type()

Get the database type

Usage

TblSqlSource$get_db_type()

Returns

A string describing the database type (e.g., "DuckDB", "SQLite")

Method get_schema()

Get schema information about the table

Usage

TblSqlSource$get_schema(categorical_threshold = 20)

Arguments

Returns

A string containing schema information formatted for LLM prompts

Method execute_query()

Execute a SQL query and return results

Usage

TblSqlSource$execute_query(query)

Arguments

Returns

A data frame containing query results

Method test_query()

Test a SQL query by fetching only one row

Usage

TblSqlSource$test_query(query, require_all_columns = FALSE)

Arguments

Returns

A data frame containing one row of results (or empty if no matches)

Method prep_query()

Prepare a generic ⁠SELECT * FROM ____⁠ query to work with the SQL tibble

Usage

TblSqlSource$prep_query(query)

Arguments

Returns

A complete SQL query string

Method get_data()

Get the unfiltered data as a SQL tibble

Usage

TblSqlSource$get_data()

Returns

A dbplyr::tbl_sql() containing the original, unfiltered data

Method cleanup()

Clean up resources (close connections, etc.)

Usage

TblSqlSource$cleanup()

Returns

NULL (invisibly)

Method clone()

The objects of this class are cloneable with this method.

Usage

TblSqlSource$clone(deep = FALSE)

Arguments

Examples

con <- DBI::dbConnect(duckdb::duckdb())
DBI::dbWriteTable(con, "mtcars", mtcars)

mtcars_source <- TblSqlSource$new(dplyr::tbl(con, "mtcars"))
mtcars_source$get_db_type()  # "DuckDB"

result <- mtcars_source$execute_query("SELECT * FROM mtcars WHERE cyl > 4")

# Note, the result is not the *full* data frame, but a lazy SQL tibble
result

# You can chain this result into a dplyr pipeline
dplyr::count(result, cyl, gear)

# Or collect the entire data frame into local memory
dplyr::collect(result)

# Finally, clean up when done with the database (closes the DB connection)
mtcars_source$cleanup()

Deprecated functions

Description

These functions have been replaced by the new QueryChat R6 class API. Please update your code to use the new class-based approach.

Usage

querychat_init(...)

querychat_sidebar(...)

querychat_ui(...)

querychat_server(...)

querychat_greeting(...)

querychat_data_source(...)

Value

Please see the updated function details for return values.

Functions

• querychat_init(): was replaced with the ⁠$new()⁠ method of QueryChat.

• querychat_sidebar(): was replaced with the ⁠$sidebar()⁠ method of QueryChat.

• querychat_ui(): was replaced with the ⁠$ui()⁠ method of QueryChat.

• querychat_server(): was replaced with the ⁠$server()⁠ method of QueryChat.

• querychat_greeting(): was replaced with the ⁠$generate_greeting()⁠ method of QueryChat.

• querychat_data_source(): was replaced with the ⁠$new()⁠ method of QueryChat.

QueryChat convenience functions

Description

Convenience functions for wrapping QueryChat creation (i.e., querychat()) and app launching (i.e., querychat_app()).

Usage

querychat(
  data_source,
  table_name = missing_arg(),
  ...,
  id = NULL,
  greeting = NULL,
  client = NULL,
  tools = c("update", "query"),
  data_description = NULL,
  categorical_threshold = 20,
  extra_instructions = NULL,
  prompt_template = NULL,
  cleanup = NA
)

querychat_app(
  data_source,
  table_name = missing_arg(),
  ...,
  id = NULL,
  greeting = NULL,
  client = NULL,
  tools = c("update", "query"),
  data_description = NULL,
  categorical_threshold = 20,
  extra_instructions = NULL,
  prompt_template = NULL,
  cleanup = NA,
  bookmark_store = "url"
)

Arguments

Value

A QueryChat object. See QueryChat for available methods.

Invisibly returns the chat object after the app stops.

Examples

# Quick start - chat with mtcars dataset in one line
querychat_app(mtcars)

# Add options
querychat_app(
  mtcars,
  greeting = "Welcome to the mtcars explorer!",
  client = "openai/gpt-4o"
)

# Chat with a database table (table_name required)
con <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
DBI::dbWriteTable(con, "mtcars", mtcars)
querychat_app(con, "mtcars")

# Create QueryChat class object
qc <- querychat(mtcars, greeting = "Welcome to the mtcars explorer!")

# Run the app later
qc$app()