QueryChat

https://posit-dev.github.io/querychat/
Admin
QueryChat facilitates safe and reliable natural language exploration of tabular data, powered by SQL...
Tokens:36,470
Snippets:480
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### QueryChat usage examples

Source: https://posit-dev.github.io/querychat/r/reference/querychat-convenience.html

Examples demonstrating quick start, configuration options, database connectivity, and manual object creation.

```R
if (FALSE) { # rlang::is_interactive() && rlang::is_installed("RSQLite")
# 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()
}
```

--------------------------------

### Install querychat

Source: https://posit-dev.github.io/querychat/py/index.html

Install the latest stable version of the library from PyPI.

```bash
pip install querychat
```

--------------------------------

### DBISource Usage Example

Source: https://posit-dev.github.io/querychat/r/reference/DBISource.html

A complete example demonstrating connection, initialization, querying, and cleanup.

```R
# 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"
#> [1] "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()
```

--------------------------------

### Install Visualization Dependencies

Source: https://posit-dev.github.io/querychat/py/visualize.html

Install the necessary extras to enable visualization support.

```bash
pip install "querychat[viz]"
```

--------------------------------

### Install querychat

Source: https://posit-dev.github.io/querychat/r/index.html

Installation instructions for the stable version from CRAN and the development version from GitHub.

```R
install.packages("querychat")
```

```R
# install.packages("pak")
pak::pak("posit-dev/querychat/pkg-r")
```

--------------------------------

### Install QueryChat with framework dependencies

Source: https://posit-dev.github.io/querychat/py/index.html

Install the core package along with the specific framework support required.

```bash
pip install "querychat[streamlit]"  # or [gradio] or [dash]__
```

--------------------------------

### Install QueryChat with Dash support

Source: https://posit-dev.github.io/querychat/py/build-dash.html

Install the necessary package to enable Dash integration.

```bash
pip install "querychat[dash]"
```

--------------------------------

### Install QueryChat with Gradio support

Source: https://posit-dev.github.io/querychat/py/build-gradio.html

Install the necessary package to enable Gradio integration.

```bash
pip install "querychat[gradio]"
```

--------------------------------

### Install QueryChat pins support

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Install the necessary dependencies to enable pins support.

```bash
pip install querychat[pins]
```

--------------------------------

### Install Framework Dependencies

Source: https://posit-dev.github.io/querychat/py/CHANGELOG.html

Install the necessary dependencies for specific web frameworks using pip extras.

```bash
pip install querychat[gradio]
```

```bash
pip install querychat[dash]
```

```bash
pip install querychat[streamlit]
```

--------------------------------

### Run the Dash application

Source: https://posit-dev.github.io/querychat/py/build-dash.html

Execute the Python script to start the Dash server.

```bash
python dash-app.py
```

--------------------------------

### Load required libraries

Source: https://posit-dev.github.io/querychat/r/articles/models.html

Initial setup to load the querychat, palmerpenguins, and ellmer packages.

```r
library(querychat)
library(palmerpenguins)
library(ellmer)
```

--------------------------------

### Install Ibis BigQuery

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Install the necessary dependencies for BigQuery backend support.

```bash
pip install ibis-framework[bigquery]
```

--------------------------------

### Install ggsql Package

Source: https://posit-dev.github.io/querychat/r/articles/tools.html

Install the ggsql package required for enabling visualization tools.

```R
install.packages("ggsql")
```

--------------------------------

### TblSqlSource Usage Example

Source: https://posit-dev.github.io/querychat/r/reference/TblSqlSource.html

Demonstrates connecting to a DuckDB database, creating a source, and executing a query.

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

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

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

--------------------------------

### Build Complete Dashboard

Source: https://posit-dev.github.io/querychat/py/build-streamlit.html

A comprehensive example combining metrics, multiple visualizations, and a custom sidebar reset button.

```python
import plotly.express as px
from querychat.data import titanic
from querychat.streamlit import QueryChat

import streamlit as st

st.set_page_config(page_title="Titanic Explorer", layout="wide")

qc = QueryChat(titanic(), "titanic")

# Sidebar with chat and reset
with st.sidebar:
    qc.ui()
    st.divider()
    if st.button("Reset Filters", use_container_width=True):
        qc.reset()

# Main content
st.header(qc.title() or "Titanic Dataset")

# Metrics row
df = qc.df().to_pandas()
col1, col2, col3 = st.columns(3)
col1.metric("Passengers", len(df))
col2.metric("Survivors", df["survived"].sum())
col3.metric("Survival Rate", f"{df['survived'].mean():.1%}")

# Visualizations
col1, col2 = st.columns(2)

with col1:
    fig1 = px.histogram(
        df, x="age", color="survived", title="Age Distribution by Survival"
    )
    st.plotly_chart(fig1, use_container_width=True)

with col2:
    fig2 = px.bar(
        df.groupby("pclass")["survived"].mean().reset_index(),
        x="pclass",
        y="survived",
        title="Survival by Class",
    )
    st.plotly_chart(fig2, use_container_width=True)
```

--------------------------------

### Install Ibis PostgreSQL

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Install the necessary dependencies for PostgreSQL backend support.

```bash
pip install ibis-framework[postgres]
```

--------------------------------

### Run the Gradio application

Source: https://posit-dev.github.io/querychat/py/build-gradio.html

Execute the Python script to start the Gradio server.

```bash
python gradio-app.py
```

--------------------------------

### Install QueryChat with Streamlit support

Source: https://posit-dev.github.io/querychat/py/build-streamlit.html

Use this command to install the necessary dependencies for Streamlit integration.

```bash
pip install "querychat[streamlit]"
```

--------------------------------

### Install DuckDB dependencies

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Install the necessary packages for DuckDB support.

```bash
pip install duckdb duckdb-engine
```

--------------------------------

### Install Ibis DuckDB

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Install the necessary dependencies for DuckDB backend support.

```bash
pip install ibis-framework[duckdb]
```

--------------------------------

### Connect QueryChat to MySQL

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Install pymysql and initialize QueryChat with a MySQL engine.

```bash
pip install pymysql
```

```python
from sqlalchemy import create_engine
from querychat import QueryChat

engine = create_engine("mysql+pymysql://user:password@localhost:3306/mydatabase")
qc = QueryChat(engine, "my_table")
app = qc.app()__
```

--------------------------------

### Install and load dotenv

Source: https://posit-dev.github.io/querychat/py/models.html

Use the dotenv package to load environment variables from a .env file.

```bash
pip install dotenv
```

```python
from dotenv import load_dotenv
load_dotenv()
```

--------------------------------

### Build a Complete Dashboard with Metrics and Charts

Source: https://posit-dev.github.io/querychat/py/build-gradio.html

A comprehensive example integrating metrics, titles, and multiple visualizations into a single Gradio app.

```python
import plotly.express as px
from querychat.data import titanic
from querychat.gradio import QueryChat
from querychat.types import AppStateDict

import gradio as gr

qc = QueryChat(titanic(), "titanic")

with gr.Blocks(title="Titanic Explorer") as app:
    gr.Markdown("# Titanic Dataset Explorer")

    with gr.Row():
        with gr.Column(scale=1):
            state = qc.ui()

        with gr.Column(scale=2):
            title_display = gr.Markdown("## All Data")

            with gr.Row():
                passengers_box = gr.Textbox(label="Passengers", interactive=False)
                survivors_box = gr.Textbox(label="Survivors", interactive=False)
                rate_box = gr.Textbox(label="Survival Rate", interactive=False)

            with gr.Row():
                plot1 = gr.Plot()
                plot2 = gr.Plot()

    def update_all(state_dict: AppStateDict):
        df = qc.df(state_dict).to_pandas()
        title = qc.title(state_dict) or "All Data"

        # Metrics
        n_passengers = str(len(df))
        n_survivors = str(int(df["survived"].sum()))
        survival_rate = f"{df['survived'].mean():.1%}"

        # Visualizations
        fig1 = px.histogram(
            df, x="age", color="survived", title="Age Distribution by Survival"
        )
        fig2 = px.bar(
            df.groupby("pclass")["survived"].mean().reset_index(),
            x="pclass",
            y="survived",
            title="Survival by Class",
        )

        return (
            f"## {title}",
            n_passengers,
            n_survivors,
            survival_rate,
            fig1,
            fig2,
        )

    state.change(
        fn=update_all,
        inputs=[state],
        outputs=[
            title_display,
            passengers_box,
            survivors_box,
            rate_box,
            plot1,
            plot2,
        ],
    )

app.launch(css=qc.css, head=qc.head)
```

--------------------------------

### Connect QueryChat to PostgreSQL

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Install psycopg2-binary and initialize QueryChat with a PostgreSQL engine.

```bash
pip install psycopg2-binary
```

```python
from sqlalchemy import create_engine
from querychat import QueryChat

engine = create_engine("postgresql+psycopg2://user:password@localhost:5432/mydatabase")
qc = QueryChat(engine, "my_table")
app = qc.app()__
```

--------------------------------

### Initialize QueryChat with Gradio

Source: https://posit-dev.github.io/querychat/py/index.html

Use the Gradio-specific QueryChat class and call launch() to start the interface.

```python
from querychat.gradio import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
qc.app().launch()__
```

--------------------------------

### Initialize QueryChat with Dash

Source: https://posit-dev.github.io/querychat/py/index.html

Use the Dash-specific QueryChat class and call run() to start the application.

```python
from querychat.dash import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
qc.app().run()__
```

--------------------------------

### Initialize QueryChat Application

Source: https://posit-dev.github.io/querychat/py/tools.html

Basic setup for a QueryChat application using the titanic dataset.

```python
from querychat import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
app = qc.app()__
```

--------------------------------

### Initialize QueryChat with Data Frames

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Examples of initializing a QueryChat application using different data frame libraries.

```python
import pandas as pd
from querychat import QueryChat

mtcars = pd.read_csv(
    "https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv"
)

qc = QueryChat(mtcars, "mtcars")
app = qc.app()__
```

```python
import polars as pl
from querychat import QueryChat

mtcars = pl.read_csv(
    "https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv"
)

qc = QueryChat(mtcars, "mtcars")
app = qc.app()__
```

```python
import pyarrow as pa
import pyarrow.csv as pv
from querychat import QueryChat

mtcars = pv.read_csv(
    "https://gist.githubusercontent.com/seankross/a412dfbd88b3db70b74b/raw/5f23f993cd87c283ce766e7ac6b329ee7cc2e1d1/mtcars.csv"
).to_table()

qc = QueryChat(mtcars, "mtcars")
app = qc.app()__
```

--------------------------------

### Implement custom data source

Source: https://posit-dev.github.io/querychat/r/reference/DataSource.html

Example of inheriting from the DataSource class to create a custom implementation.

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

--------------------------------

### Launch querychat Shiny App

Source: https://posit-dev.github.io/querychat/r/index.html

Starts a pre-built Shiny application for data exploration. Requires a data source and an LLM client configuration.

```R
library(querychat)
library(palmerpenguins)

querychat_app(penguins, client = "openai/gpt-4.1")
```

--------------------------------

### DataFrameSource Usage Examples

Source: https://posit-dev.github.io/querychat/r/reference/DataFrameSource.html

Common operations including initialization, querying, and cleanup.

```R
# 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"
#> [1] "DuckDB"

# 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()
```

--------------------------------

### Configure QueryChat with extra instructions

Source: https://posit-dev.github.io/querychat/py/context.html

Use the extra_instructions parameter to guide LLM behavior via a file or a string.

```python
qc = QueryChat(
    titanic,
    "titanic",
    extra_instructions=Path("instructions.md")
)__
```

```python
instructions = """
- Use British spelling conventions
- Stay on topic and only discuss the data
- Refuse to answer unrelated questions
"""

qc = QueryChat(titanic, "titanic", extra_instructions=instructions)__
```

--------------------------------

### Launch interactive console

Source: https://posit-dev.github.io/querychat/py/reference/express.QueryChat.html

Starts an interactive console chat session with the data.

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

--------------------------------

### Add custom instructions

Source: https://posit-dev.github.io/querychat/r/articles/context.html

Guide the LLM's behavior by passing a file path or a string to the extra_instructions parameter.

```R
qc <- querychat(
  penguins,
  extra_instructions = "instructions.md"
)

cat(qc$system_prompt)
```

```R
instructions <- "
- Use British spelling conventions
- Stay on topic and only discuss the data dashboard
- Refuse to answer unrelated questions
"

qc <- querychat(
  penguins,
  extra_instructions = instructions
)

cat(qc$system_prompt)
```

--------------------------------

### Connect to GitHub model marketplace

Source: https://posit-dev.github.io/querychat/r/articles/models.html

Initialize a client using GitHub credentials, assuming GITHUB_TOKEN is set in the environment.

```r
library(ellmer)

# Just works if GITHUB_TOKEN is set in your environment
client <- chat_github(model = "gpt-4.1")
```

--------------------------------

### Initialize ChatPosit client

Source: https://posit-dev.github.io/querychat/py/models.html

Use ChatPosit for free trial access; it prompts for OAuth login and caches tokens.

```python
from chatlas import ChatPosit

# Prompts you to log in via OAuth the first time; tokens are then cached
client = ChatPosit()
```

--------------------------------

### Initializing QueryChat with DataDict

Source: https://posit-dev.github.io/querychat/py/CHANGELOG.html

Load table and column descriptions from a YAML file to provide context to the LLM.

```python
QueryChat(data_dict="data_dict.yaml")__
```

--------------------------------

### express.QueryChat.table

Source: https://posit-dev.github.io/querychat/py/reference/express.QueryChat.html

Get a per-table accessor with reactive state.

```APIDOC
## express.QueryChat.table

### Description
Get a per-table accessor with reactive state.

### Parameters
- **name** (str) - Required - Table name (must match a name passed to add_table()).

### Returns
- **TableAccessor** - Accessor with df(), sql(), and title() backed by per-session reactive state.
```

--------------------------------

### Initialize QueryChat with a greeting file

Source: https://posit-dev.github.io/querychat/py/greet.html

Pass a path to a markdown file to the greeting parameter to avoid auto-generating instructions on every user arrival.

```python
from querychat import QueryChat
from querychat.data import titanic
from pathlib import Path

app_dir = Path(__file__).parent

qc = QueryChat(titanic(), "titanic", greeting=app_dir / "greeting.md")
app = qc.app()
```

--------------------------------

### Initialize QueryChat with Visualization

Source: https://posit-dev.github.io/querychat/py/visualize.html

Configure QueryChat to include the visualize tool during initialization.

```python
from querychat import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic", tools=("query", "update", "visualize"))
app = qc.app()
```

```python
qc = QueryChat(titanic(), "titanic", tools=("query", "visualize"))
```

--------------------------------

### Get unfiltered data

Source: https://posit-dev.github.io/querychat/r/reference/DataSource.html

Retrieves all data from the table as a data frame.

```R
DataSource$get_data()
```

--------------------------------

### Get All Table Data

Source: https://posit-dev.github.io/querychat/r/reference/DBISource.html

Retrieve the entire dataset from the configured table.

```R
DBISource$get_data()
```

--------------------------------

### Get Database Type

Source: https://posit-dev.github.io/querychat/r/reference/DBISource.html

Retrieve the database type identifier from the connection.

```R
DBISource$get_db_type()
```

--------------------------------

### Initialize and integrate querychat in a Shiny app

Source: https://posit-dev.github.io/querychat/r/articles/build.html

A starter template demonstrating the three-step integration process: initializing the QueryChat instance, adding the UI component, and using reactive values in the server function.

```R
library(shiny)
library(bslib)
library(querychat)
library(DT)
library(palmerpenguins)

# Step 1: Initialize QueryChat
qc <- QueryChat$new(penguins)

# Step 2: Add UI component
ui <- page_sidebar(
  sidebar = qc$sidebar(),
  card(
    card_header("Data Table"),
    dataTableOutput("table")
  ),
  card(
    fill = FALSE,
    card_header("SQL Query"),
    verbatimTextOutput("sql")
  )
)

# Step 3: Use reactive values in server
server <- function(input, output, session) {
  qc_vals <- qc$server()
  
  output$table <- renderDataTable({
    datatable(qc_vals$df(), fillContainer = TRUE)
  })

  output$sql <- renderText({
    qc_vals$sql() %||% "SELECT * FROM penguins"
  })
}

shinyApp(ui, server)
```

--------------------------------

### Configure QueryChat with Visualization Tools

Source: https://posit-dev.github.io/querychat/r/articles/tools.html

Initialize a QueryChat instance with specific tools enabled, including the visualization tool.

```R
library(palmerpenguins)

qc <- QueryChat$new(
  penguins,
  tools = c("query", "update", "visualize")
)
qc$app()
```

--------------------------------

### Initialize QueryChat with a data source

Source: https://posit-dev.github.io/querychat/py/build-streamlit.html

Create a QueryChat instance by providing a data source and a name.

```python
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
```

--------------------------------

### Get schema information

Source: https://posit-dev.github.io/querychat/r/reference/DataSource.html

Retrieves schema information formatted for LLM prompts.

```R
DataSource$get_schema(categorical_threshold = 20)
```

--------------------------------

### Initialize QueryChat client

Source: https://posit-dev.github.io/querychat/py/reference/QueryChat.html

Creates a chat client with specified tools and optional dashboard callbacks.

```python
QueryChat.client(
    tools=MISSING,
    update_dashboard=None,
    reset_dashboard=None,
    visualize=None,
)__
```

--------------------------------

### Configure a static greeting file

Source: https://posit-dev.github.io/querychat/r/articles/greet.html

Pass a markdown file path to the greeting argument to avoid auto-generating instructions on every app launch.

```R
qc <- querychat(
  penguins,
  greeting = "greeting.md"
)
qc$app()  # Launch the app
```

--------------------------------

### Initialize querychat with data

Source: https://posit-dev.github.io/querychat/r/articles/context.html

Load the necessary libraries to begin using querychat with a dataset.

```R
library(querychat)
library(palmerpenguins)
```

--------------------------------

### Get current table name

Source: https://posit-dev.github.io/querychat/py/reference/types.ServerValues.html

Retrieves the name of the most recently queried table reactively.

```python
types.ServerValues.current_table()__
```

--------------------------------

### Initialize QueryChat Application

Source: https://posit-dev.github.io/querychat/py/index.html

Create a QueryChat instance with a data source and launch the default Shiny application.

```python
from querychat import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
app = qc.app()
```

--------------------------------

### Create a complete Dash application with QueryChat

Source: https://posit-dev.github.io/querychat/py/build-dash.html

Initializes a QueryChat instance with the Titanic dataset and sets up a Dash layout with metrics and charts that update based on the chat state.

```python
import dash_bootstrap_components as dbc
import plotly.express as px
from querychat.dash import QueryChat
from querychat.data import titanic
from querychat.types import AppStateDict

from dash import Dash, Input, Output, dcc, html

qc = QueryChat(titanic(), "titanic")

app = Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])

app.layout = dbc.Container(
    [
        html.H1("Titanic Dataset Explorer", className="my-3"),
        dbc.Row(
            [
                dbc.Col(qc.ui(), width=4),
                dbc.Col(
                    [
                        html.H3(id="data-title", className="mb-3"),
                        dbc.Row(
                            [
                                dbc.Col(
                                    dbc.Card(
                                        [
                                            dbc.CardHeader("Passengers"),
                                            dbc.CardBody(
                                                html.H4(id="metric-passengers")
                                            ),
                                        ]
                                    )
                                ),
                                dbc.Col(
                                    dbc.Card(
                                        [
                                            dbc.CardHeader("Survivors"),
                                            dbc.CardBody(
                                                html.H4(id="metric-survivors")
                                            ),
                                        ]
                                    )
                                ),
                                dbc.Col(
                                    dbc.Card(
                                        [
                                            dbc.CardHeader("Survival Rate"),
                                            dbc.CardBody(html.H4(id="metric-rate")),
                                        ]
                                    )
                                ),
                            ],
                            className="mb-3",
                        ),
                        dbc.Row(
                            [
                                dbc.Col(dcc.Graph(id="age-chart")),
                                dbc.Col(dcc.Graph(id="class-chart")),
                            ]
                        ),
                    ],
                    width=8,
                ),
            ]
        ),
    ],
    fluid=True,
)

qc.init_app(app)


@app.callback(
    [
        Output("data-title", "children"),
        Output("metric-passengers", "children"),
        Output("metric-survivors", "children"),
        Output("metric-rate", "children"),
        Output("age-chart", "figure"),
        Output("class-chart", "figure"),
    ],
    Input(qc.store_id, "data"),
)
def update_all(state: AppStateDict):
    df = qc.df(state).to_pandas()
    title = qc.title(state) or "All Data"

    # Metrics
    n_passengers = len(df)
    n_survivors = int(df["survived"].sum())
    survival_rate = f"{df['survived'].mean():.1%}"

    # Charts
    fig1 = px.histogram(
        df, x="age", color="survived", title="Age Distribution by Survival"
    )
    fig2 = px.bar(
        df.groupby("pclass")["survived"].mean().reset_index(),
        x="pclass",
        y="survived",
        title="Survival by Class",
    )

    return (
        title,
        n_passengers,
        n_survivors,
        survival_rate,
        fig1,
        fig2,
    )


if __name__ == "__main__":
    import os

    port = int(os.environ.get("DASH_PORT", "8050"))
    debug = os.environ.get("DASH_DEBUG", "true").lower() == "true"
    app.run(debug=debug, port=port)
```

--------------------------------

### Initialize QueryChat with visualization

Source: https://posit-dev.github.io/querychat/r/articles/visualize.html

Configure QueryChat to include the 'visualize' tool alongside standard data tools.

```R
library(querychat)
library(palmerpenguins)

qc <- QueryChat$new(
  penguins,
  tools = c("query", "update", "visualize")
)
qc$app()
```

```R
qc <- QueryChat$new(
  penguins,
  tools = c("query", "visualize")
)
```

--------------------------------

### Get Semantic Views Description

Source: https://posit-dev.github.io/querychat/r/reference/DBISource.html

Retrieve information about semantic views for use in system prompts.

```R
DBISource$get_semantic_views_description()
```

--------------------------------

### Create a pre-baked Streamlit app

Source: https://posit-dev.github.io/querychat/py/build-streamlit.html

Use the .app() method to quickly generate a complete Streamlit interface.

```python
from querychat.streamlit import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
qc.app()
```

--------------------------------

### Create a chat client

Source: https://posit-dev.github.io/querychat/py/reference/express.QueryChat.html

Initializes a chat client with specific tools and optional callback functions for dashboard updates.

```python
express.QueryChat.client(
    tools=MISSING,
    update_dashboard=None,
    reset_dashboard=None,
    visualize=None,
)__
```

--------------------------------

### Get Schema Information

Source: https://posit-dev.github.io/querychat/r/reference/DBISource.html

Retrieve schema details, with an optional threshold for identifying categorical text columns.

```R
DBISource$get_schema(categorical_threshold = 20)
```

--------------------------------

### Get table accessor

Source: https://posit-dev.github.io/querychat/py/reference/express.QueryChat.html

Returns a reactive accessor for a specific table, enabling per-session state management.

```python
express.QueryChat.table(name)__
```

```python
from querychat.express import QueryChat
from shiny.express import render

qc = QueryChat(orders, "orders")
qc.add_table(customers, "customers")
qc.sidebar()


@render.data_frame
def orders_table():
    return qc.table("orders").df()


@render.data_frame
def customers_table():
    return qc.table("customers").df()__
```

--------------------------------

### Launch a pre-baked Gradio app

Source: https://posit-dev.github.io/querychat/py/build-gradio.html

Use the .app() method to quickly generate and launch a complete Gradio interface.

```python
from querychat.gradio import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
app = qc.app()
app.launch()
```

--------------------------------

### Remove a table

Source: https://posit-dev.github.io/querychat/py/reference/express.QueryChat.html

Removes a registered table from the QueryChat instance. Raises errors if the table is missing or if called after the server has started.

```python
express.QueryChat.remove_table(table_name)__
```

--------------------------------

### Create a chat client

Source: https://posit-dev.github.io/querychat/r/reference/QueryChat.html

Configures a chat client with registered tools for the current data source. Requires defining callback functions for dashboard updates and visualizations.

```R
QueryChat$client(
  tools = NA,
  update_dashboard = function(query, title) {
 },
  reset_dashboard = function() {
 },
  visualize = function(data) {
 },
  session = NULL
)
```

--------------------------------

### Define a Data Dictionary in YAML

Source: https://posit-dev.github.io/querychat/py/context.html

Structure your data dictionary with tables, relationships, and a glossary to guide the LLM's SQL generation.

```yaml
version: "0.2.0"

tables:
  orders:
    description: One row per customer order.
    columns:
      - name: order_id
        type: number(id)
        constraints: [primary_key]
        description: Unique order identifier.
      - name: customer_id
        type: number(id)
        constraints: [foreign_key]
        description: References customers.id.
      - name: total
        type: number(quantity)
        description: Order total in USD.
      - name: status
        type: enum
        values: [pending, shipped, delivered, cancelled]
        description: Current order status.

  customers:
    description: One row per customer.
    columns:
      - name: id
        type: number(id)
        constraints: [primary_key]
        description: Unique customer identifier.
      - name: name
        type: string
        description: Full name.
      - name: region
        type: string
        description: Geographic sales region.

relationships:
  - description: Each order belongs to one customer.
    cardinality: many-to-one
    join: orders.customer_id = customers.id

glossary:
  AOV: Average order value — total revenue divided by number of orders.
  churn: A customer who has not placed an order in the last 90 days.
```

--------------------------------

### Initialize QueryChat with deferred data sources

Source: https://posit-dev.github.io/querychat/r/articles/build.html

Demonstrates initializing a QueryChat instance without an immediate data source, allowing for data to be provided later within an active Shiny session.

```R
library(shiny)
library(bslib)
library(querychat)
```

--------------------------------

### Standalone Chat Client and Console Usage

Source: https://posit-dev.github.io/querychat/py/reference/QueryChat.html

Use QueryChat as a standalone client to programmatically query data or start an interactive console session.

```python
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()
```

--------------------------------

### Create a Basic Gradio Layout with QueryChat

Source: https://posit-dev.github.io/querychat/py/build-gradio.html

Demonstrates placing a QueryChat interface alongside a data table using Gradio Blocks.

```python
import gradio as gr
from querychat.gradio import QueryChat
from querychat.data import titanic
from querychat.types import AppStateDict

qc = QueryChat(titanic(), "titanic")

with gr.Blocks() as app:
    with gr.Row():
        with gr.Column():
            state = qc.ui()

        with gr.Column():
            data_table = gr.Dataframe(label="Data")

    def update_table(state_dict: AppStateDict):
        return qc.df(state_dict).to_pandas()

    state.change(fn=update_table, inputs=[state], outputs=[data_table])

app.launch(css=qc.css, head=qc.head)
```

--------------------------------

### Deferred Data Source Initialization in Core

Source: https://posit-dev.github.io/querychat/py/build.html

Initialize QueryChat without a data source and provide it via qc.server() in the server function.

```python
from shiny import App, ui
from querychat import QueryChat

# Global scope - create QueryChat without data source
qc = QueryChat(None, "users")

app_ui = ui.page_sidebar(
    qc.sidebar(),
    ui.output_data_frame("table"),
)

def server(input, output, session):
    # Server scope - create connection with session credentials
    conn = get_user_connection(session)
    qc_vals = qc.server(data_source=conn)

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

app = App(app_ui, server)
```

--------------------------------

### Initialize a QueryChat app

Source: https://posit-dev.github.io/querychat/py/reference/QueryChat.html

Creates a Shiny application with a chat sidebar and data view for quick interaction.

```python
QueryChat.app(history=None)__
```

--------------------------------

### Create a Dash app with QueryChat

Source: https://posit-dev.github.io/querychat/py/build-dash.html

Use the .app() method to generate a pre-configured Dash application.

```python
from querychat.dash import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
app = qc.app()

if __name__ == "__main__":
    app.run(debug=True)
```

--------------------------------

### Initialize QueryChat with a Data Dictionary

Source: https://posit-dev.github.io/querychat/py/context.html

Configure a QueryChat instance by passing a path to a YAML data dictionary file.

```python
from pathlib import Path
from querychat import QueryChat

qc = QueryChat(
    orders, "orders",
    data_dict=Path("data-dict.yaml")
)
qc.add_table(customers, "customers")
```

--------------------------------

### Initialize DBISource

Source: https://posit-dev.github.io/querychat/r/reference/DBISource.html

Create a new instance of DBISource using a DBI connection and a target table name.

```R
DBISource$new(conn, table_name)
```

--------------------------------

### Connect to PostgreSQL with QueryChat

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Initialize a QueryChat application using an Ibis PostgreSQL connection.

```python
import ibis
from querychat import QueryChat

# Connect to PostgreSQL
conn = ibis.postgres.connect(
    host="localhost",
    port=5432,
    database="mydatabase",
    user="user",
    password="password",
)
table = conn.table("my_table")

qc = QueryChat(table, "my_table")
app = qc.app()__
```

--------------------------------

### Creating LazyFrames from various sources

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Shows different methods to initialize a LazyFrame from parquet, CSV, multiple files, or an existing DataFrame.

```python
# From parquet (most efficient)
lf = pl.scan_parquet("data.parquet")

# From CSV
lf = pl.scan_csv("data.csv")

# From multiple files
lf = pl.scan_parquet("data/*.parquet")

# From an existing DataFrame
df = pl.read_csv("data.csv")
lf = df.lazy()
```

--------------------------------

### Initialize QueryChat Server Logic

Source: https://posit-dev.github.io/querychat/r/reference/QueryChat.html

Sets up reactive server logic for the chat interface within a Shiny server function.

```R
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")
}
```

--------------------------------

### Initialize TblSqlSource

Source: https://posit-dev.github.io/querychat/r/reference/TblSqlSource.html

Create a new instance of TblSqlSource using a database-backed tibble.

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

--------------------------------

### Run the Streamlit application

Source: https://posit-dev.github.io/querychat/py/build-streamlit.html

Execute the application using the Streamlit CLI.

```bash
streamlit run streamlit-app.py
```

--------------------------------

### QueryChat$server()

Source: https://posit-dev.github.io/querychat/r/reference/QueryChat.html

Initializes the server-side logic for QueryChat and returns reactive values.

```APIDOC
## QueryChat$server()

### Description
Sets up the server logic for the QueryChat instance. It returns a list of reactive values including the generated SQL query ($sql()) and the resulting data ($df()).
```

--------------------------------

### Initialize QueryChat in a Shiny App

Source: https://posit-dev.github.io/querychat/r/articles/build.html

Demonstrates creating a QueryChat instance and integrating it into a Shiny UI and server function.

```R
qc <- QueryChat$new(NULL, "users")

ui <- page_sidebar(
  sidebar = qc$sidebar(),
  card(dataTableOutput("table"))
)

server <- function(input, output, session) {
  # Server scope - create connection with session credentials
  conn <- get_user_connection(session)
  qc_vals <- qc$server(data_source = conn)

  output$table <- renderDataTable({
    qc_vals$df()
  })
}

shinyApp(ui, server)
```

--------------------------------

### Run QueryChat Application

Source: https://posit-dev.github.io/querychat/r/articles/tools.html

Launch a pre-built QueryChat application using the provided dataset.

```R
querychat_app(penguins)
```

--------------------------------

### Build a complex QueryChat dashboard with value boxes

Source: https://posit-dev.github.io/querychat/r/articles/build.html

Demonstrates a dashboard layout using bslib value boxes and multiple Plotly visualizations to summarize filtered data.

```R
library(shiny)
library(bslib)
library(DT)
library(plotly)
library(palmerpenguins)
library(dplyr)
library(bsicons)
library(querychat)


qc <- QueryChat$new(penguins)

ui <- page_sidebar(
  title = "Palmer Penguins Analysis",
  class = "bslib-page-dashboard",
  sidebar = qc$sidebar(),
  layout_column_wrap(
    width = 1 / 3,
    fill = FALSE,
    value_box(
      title = "Total Penguins",
      value = textOutput("count"),
      showcase = bs_icon("piggy-bank"),
      theme = "primary"
    ),
    value_box(
      title = "Species Count",
      value = textOutput("species_count"),
      showcase = bs_icon("bookmark-star"),
      theme = "success"
    ),
    value_box(
      title = "Avg Body Mass",
      value = textOutput("avg_mass"),
      showcase = bs_icon("speedometer"),
      theme = "info"
    )
  ),
  layout_columns(
    card(
      card_header(textOutput("table_title")),
      DT::dataTableOutput("data_table")
    ),
    card(
      card_header("Species Distribution"),
      plotlyOutput("species_plot")
    )
  ),
  layout_columns(
    card(
      card_header("Bill Length Distribution"),
      plotlyOutput("bill_length_dist")
    ),
    card(
      card_header("Body Mass by Species"),
      plotlyOutput("mass_by_species")
    )
  )
)

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

  output$count <- renderText({
    nrow(qc_vals$df())
  })

  output$species_count <- renderText({
    length(unique(qc_vals$df()$species))
  })

  output$avg_mass <- renderText({
    avg <- mean(qc_vals$df()$body_mass_g, na.rm = TRUE)
    paste0(round(avg, 0), "g")
  })

  output$table_title <- renderText({
    qc_vals$title() %||% "All Penguins"
  })

  output$data_table <- DT::renderDataTable({
    DT::datatable(
      qc_vals$df(),
      fillContainer = TRUE,
      options = list(
        scrollX = TRUE,
        pageLength = 10,
        dom = "ti"
      )
    )
  })

  output$species_plot <- renderPlotly({
    plot_ly(
      count(qc_vals$df(), species),
      x = ~species,
      y = ~n,
      type = "bar",
      marker = list(color = c("#1f77b4", "#ff7f0e", "#2ca02c"))
    )
  })

  output$bill_length_dist <- renderPlotly({
    plot_ly(
      qc_vals$df(),
      x = ~bill_length_mm,
      type = "histogram",
      nbinsx = 30,
      marker = list(color = "#1f77b4", opacity = 0.7)
    )
  })

  output$mass_by_species <- renderPlotly({
    plot_ly(
      qc_vals$df(),
      x = ~species,
      y = ~body_mass_g,
      color = ~sex,
      type = "box",
      colors = c("#1f77b4", "#ff7f0e")
    )
  })
}

shinyApp(ui = ui, server = server)
```

--------------------------------

### Connect to BigQuery with QueryChat

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Initialize a QueryChat application using an Ibis BigQuery connection.

```python
import ibis
from querychat import QueryChat

# Connect to BigQuery (uses default credentials from environment)
conn = ibis.bigquery.connect(
    project_id="my-project",
    dataset_id="my_dataset",
)
table = conn.table("my_table")

qc = QueryChat(table, "my_table")
app = qc.app()__
```

--------------------------------

### QueryChat.server

Source: https://posit-dev.github.io/querychat/py/reference/QueryChat.html

Initializes Shiny server logic for the QueryChat instance.

```APIDOC
## QueryChat.server(client, history, enable_bookmarking, id)

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

### Parameters
- **client** (chatlas.Chat) - Optional - Optional chat client to use for this session.
- **history** (Optional[bool | HistoryOptions]) - Optional - Conversation history configuration.
- **enable_bookmarking** (bool) - Optional - Deprecated. Use history= instead.
- **id** (Optional[str]) - Optional - Optional module ID for the QueryChat instance.

### Returns
- **ServerValues** - A ServerValues dataclass containing session-specific reactive values and the chat client.
```

--------------------------------

### Run the Shiny Application

Source: https://posit-dev.github.io/querychat/py/index.html

Execute the application using the shiny CLI tool.

```bash
shiny run --reload app.py
```

--------------------------------

### TblSqlSource$prep_query()

Source: https://posit-dev.github.io/querychat/r/reference/TblSqlSource.html

Prepares a query for the SQL tibble.

```APIDOC
## TblSqlSource$prep_query(query)

### Description
Prepare a generic SELECT * FROM ____ query to work with the SQL tibble.

### Arguments
- **query** (string) - Required - SQL query as a string.

### Returns
A complete SQL query string.
```

--------------------------------

### Initialize QueryChat with Streamlit

Source: https://posit-dev.github.io/querychat/py/index.html

Use the Streamlit-specific QueryChat class to launch an application.

```python
from querychat.streamlit import QueryChat
from querychat.data import titanic

qc = QueryChat(titanic(), "titanic")
qc.app()__
```

--------------------------------

### express.QueryChat(data_source=None, table_name=None, *, id=None, greeting=None, client=None, tools=DEFAULT_TOOLS, data_dict=None, extra_instructions=None, prompt_template=None, categorical_threshold=20, data_description=None, history=None, enable_bookmarking='auto')

Source: https://posit-dev.github.io/querychat/py/reference/express.QueryChat.html

Initializes a new QueryChat instance for use within a Shiny Express application.

```APIDOC
## express.QueryChat

### Description
Initializes a QueryChat module for Shiny Express. This class automatically registers the necessary server components for chat-based data interaction.

### Parameters
- **data_source** (IntoFrame | sqlalchemy.Engine | ibis.Table | None) - Optional - A Narwhals-compatible data frame or SQLAlchemy engine to query against.
- **table_name** (str) - Optional - The name of the table to refer to in SQL queries.
- **id** (Optional[str]) - Optional - Unique identifier for the module.
- **greeting** (Optional[str | Path]) - Optional - Initial message in Markdown or path to a file containing the greeting.
- **client** (Optional[str | chatlas.Chat]) - Optional - Chat provider/model configuration or chatlas.Chat object.
- **data_dict** (DataDict | str | Path) - Optional - Metadata for tables and columns to improve LLM context.
- **extra_instructions** (Optional[str | Path]) - Optional - Additional instructions for the chat model.
- **prompt_template** (Optional[str | Path]) - Optional - Custom system prompt template.
- **categorical_threshold** (int) - Optional - Threshold for unique values to determine categorical columns (default: 20).
- **data_description** (Optional[str | Path]) - Optional - Plain-text or Markdown description of the data.
```

--------------------------------

### QueryChat$client()

Source: https://posit-dev.github.io/querychat/r/reference/QueryChat.html

Configures and returns a chat client with registered tools for the current data source.

```APIDOC
## QueryChat$client()

### Description
Creates a chat client, complete with registered tools, for the current data source.

### Arguments
- **tools** (vector) - Optional - Tools to include (e.g., "filter", "query").
- **update_dashboard** (function) - Optional - Callback for dashboard updates.
- **reset_dashboard** (function) - Optional - Callback for dashboard resets.
- **visualize** (function) - Optional - Callback for visualization rendering.
- **session** (Shiny session) - Optional - Required for interactive chart rendering.
```

--------------------------------

### Initialize a QueryChat object

Source: https://posit-dev.github.io/querychat/r/reference/QueryChat.html

Creates a new QueryChat instance. Use this to define the data source, table name, and optional chat configurations.

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

--------------------------------

### Connect QueryChat to SQLite

Source: https://posit-dev.github.io/querychat/py/data-sources.html

Initialize QueryChat with a SQLite engine.

```python
from pathlib import Path
from sqlalchemy import create_engine
from querychat import QueryChat

# Assumes my_database.db is in the same directory as this script
db_path = Path(__file__).parent / "my_database.db"
engine = create_engine(f"sqlite:///{db_path}")

qc = QueryChat(engine, "my_table")
app = qc.app()__
```

--------------------------------

### Create a custom Shiny app with visualization

Source: https://posit-dev.github.io/querychat/r/articles/visualize.html

Integrate querychat visualization into a Shiny application using bslib and standard UI components.

```R
library(shiny)
library(bslib)
library(querychat)
library(palmerpenguins)

qc <- QueryChat$new(
  penguins,
  tools = c("update", "query", "visualize"),
  data_description = paste(
    "The Palmer Penguins dataset contains measurements of bill",
    "dimensions, flipper length, body mass, sex, and species",
    "(Adelie, Chinstrap, and Gentoo) collected from three islands in",
    "the Palmer Archipelago, Antarctica."
  )
)

ui <- page_sidebar(
  title = "querychat viz demo",
  sidebar = qc$sidebar(width = 400),
  card(
    full_screen = TRUE,
    card_header("Data"),
    DT::DTOutput("dt")
  )
)

server <- function(input, output, session) {
  qc_vals <- qc$server()
  output$dt <- DT::renderDT(qc_vals$df(), fillContainer = TRUE)
}

shinyApp(ui, server)
```

--------------------------------

### Run QueryChat Shiny Gadget

Source: https://posit-dev.github.io/querychat/r/reference/QueryChat.html

Launches an interactive Shiny gadget for data chatting.

```R
library(querychat)

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

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

--------------------------------

### QueryChat$console()

Source: https://posit-dev.github.io/querychat/r/reference/QueryChat.html

Launches a console-based chat interface for interacting with the data source.

```APIDOC
## QueryChat$console()

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

--------------------------------

### DataFrameSource.__init__

Source: https://posit-dev.github.io/querychat/py/reference/types.DataFrameSource.html

Initializes a new DataFrameSource instance with a DataFrame and a table name.

```APIDOC
## DataFrameSource(df, table_name)

### Description
A DataSource implementation that wraps a DataFrame using DuckDB.
```

--------------------------------

### Initialize QueryChat in Shiny Express

Source: https://posit-dev.github.io/querychat/py/reference/express.QueryChat.html

Demonstrates how to instantiate QueryChat with a dataset and integrate it into a Shiny Express layout using sidebar and render functions.

```python
from querychat.express import QueryChat
from seaborn import load_dataset
from shiny.express import render, ui
from shinychat.types import HistoryOptions

titanic = load_dataset("titanic")

qc = QueryChat(titanic, "titanic", history=HistoryOptions(restore_mode="bookmark"))
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,
)
```

--------------------------------

### tool_visualize(executor, update_fn, *, multi_table=False)

Source: https://posit-dev.github.io/querychat/py/reference/tools.tool_visualize.html

Creates a tool that executes a ggsql query and renders the visualization.

```APIDOC
## tool_visualize

### Description
Creates a tool that executes a ggsql query and renders the visualization.

### Parameters
- **executor** (`QueryExecutor`) - Required - The query executor to query against.
- **update_fn** (Callable[[`VisualizeData`], None]) - Required - Callback function to call with VisualizeData when visualization succeeds.
- **multi_table** (bool) - Optional - Whether multiple tables are registered. Defaults to `False`.

### Returns
- **Tool** - A tool that can be registered with chatlas.
```
Tokens:
Raw