chore: sql() reactive returns NULL or None if not set (#149)

* chore: `sql()` reactive returns `NULL` or `None` if not set

* chore: Add changelog items

* chore: clean up imports

* chore(pkg-py): Merge "breaking changes" and "changes"

Author: gadenbuie

pkg-py/CHANGELOG.md

@@ -7,10 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [UNRELEASED]
 
-### Changes
+### Breaking Changes
 
 * The entire functional API (i.e., `init()`, `sidebar()`, `server()`, etc) has been hard deprecated in favor of a simpler OOP-based API. Namely, the new `QueryChat()` class is now the main entry point (instead of `init()`) and has methods to replace old functions (e.g., `.sidebar()`, `.server()`, etc). (#101)
 
+* The `.sql()` method now returns `None` instead of `""` (empty string) when no query has been set, aligning with the behavior of `.title()` for consistency. Most code using the `or` operator or `req()` for falsy checks will continue working without changes. Code that explicitly checks `sql() == ""` should be updated to use falsy checks (`if not sql()`) or explicit null checks (`if sql() is None`). (#146)
+
 ### New features
 
 * New `QueryChat.app()` method enables quicker/easier chatting with a dataset. (#104)

pkg-py/src/querychat/_querychat.py

@@ -142,7 +142,7 @@ def ui_reset():
             @reactive.effect
             @reactive.event(input.reset_query)
             def _():
-                vals.sql.set("")
+                vals.sql.set(None)
                 vals.title.set(None)
 
             @render.data_frame
@@ -586,12 +586,12 @@ def df(self) -> pd.DataFrame:
         return self._vals.df()
 
     @overload
-    def sql(self, query: None = None) -> str: ...
+    def sql(self, query: None = None) -> str | None: ...
 
     @overload
     def sql(self, query: str) -> bool: ...
 
-    def sql(self, query: Optional[str] = None) -> str | bool:
+    def sql(self, query: Optional[str] = None) -> str | None | bool:
         """
         Reactively read (or set) the current SQL query that is in effect.
 
@@ -604,7 +604,7 @@ def sql(self, query: Optional[str] = None) -> str | bool:
         -------
         :
             If no `query` is provided, returns the current SQL query as a string
-            (possibly `""` if no query has been set). If a `query` is provided,
+            (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.
 

pkg-py/src/querychat/_querychat_module.py

@@ -64,7 +64,7 @@ class ServerValues:
     sql
         A reactive Value containing the current SQL query string. Access the value
         by calling `.sql()`, or set it with `.sql.set("SELECT ...")`.
-        An empty string `""` indicates no query has been set.
+        Returns `None` if no query has been set.
     title
         A reactive Value containing the current title for the query. The LLM
         provides this title when generating a new SQL query. Access it with
@@ -78,7 +78,7 @@ class ServerValues:
     """
 
     df: Callable[[], pd.DataFrame]
-    sql: ReactiveString
+    sql: ReactiveStringOrNone
     title: ReactiveStringOrNone
     client: chatlas.Chat
 
@@ -95,7 +95,7 @@ def mod_server(
     enable_bookmarking: bool,
 ):
     # Reactive values to store state
-    sql = ReactiveString("")
+    sql = ReactiveStringOrNone(None)
     title = ReactiveStringOrNone(None)
     has_greeted = reactive.value[bool](False)  # noqa: FBT003
 
@@ -115,10 +115,11 @@ def mod_server(
     # Execute query when SQL changes
     @reactive.calc
     def filtered_df():
-        if sql.get() == "":
+        query = sql.get()
+        if not query:
             return data_source.get_data()
         else:
-            return data_source.execute_query(sql.get())
+            return data_source.execute_query(query)
 
     # Chat UI logic
     chat_ui = shinychat.Chat(CHAT_ID)

pkg-py/src/querychat/tools.py

@@ -14,7 +14,7 @@
     from collections.abc import Callable
 
     from ._datasource import DataSource
-    from ._querychat_module import ReactiveString, ReactiveStringOrNone
+    from ._querychat_module import ReactiveStringOrNone
 
 
 def _read_prompt_template(filename: str, **kwargs) -> str:
@@ -26,7 +26,7 @@ def _read_prompt_template(filename: str, **kwargs) -> str:
 
 def _update_dashboard_impl(
     data_source: DataSource,
-    current_query: ReactiveString,
+    current_query: ReactiveStringOrNone,
     current_title: ReactiveStringOrNone,
 ) -> Callable[[str, str], ContentToolResult]:
     """Create the implementation function for updating the dashboard."""
@@ -78,7 +78,7 @@ def update_dashboard(query: str, title: str) -> ContentToolResult:
 
 def tool_update_dashboard(
     data_source: DataSource,
-    current_query: ReactiveString,
+    current_query: ReactiveStringOrNone,
     current_title: ReactiveStringOrNone,
 ) -> Tool:
     """
@@ -115,14 +115,14 @@ def tool_update_dashboard(
 
 
 def _reset_dashboard_impl(
-    current_query: ReactiveString,
+    current_query: ReactiveStringOrNone,
     current_title: ReactiveStringOrNone,
 ) -> Callable[[], ContentToolResult]:
     """Create the implementation function for resetting the dashboard."""
 
     def reset_dashboard() -> ContentToolResult:
         # Reset current query and title
-        current_query.set("")
+        current_query.set(None)
         current_title.set(None)
 
         # Add Reset Filter button
@@ -151,7 +151,7 @@ def reset_dashboard() -> ContentToolResult:
 
 
 def tool_reset_dashboard(
-    current_query: ReactiveString,
+    current_query: ReactiveStringOrNone,
     current_title: ReactiveStringOrNone,
 ) -> Tool:
     """

pkg-r/NEWS.md

@@ -1,5 +1,7 @@
 # querychat (development version)
 
+* **Breaking change:** The `$sql()` method now returns `NULL` instead of `""` (empty string) when no query has been set, aligning with the behavior of `$title()` for consistency. Most code using `isTruthy()` or similar falsy checks will continue working without changes. Code that explicitly checks `sql() == ""` should be updated to use falsy checks (e.g., `!isTruthy(sql())`) or explicit null checks (`is.null(sql())`). (#146)
+
 * Tool detail cards can now be expanded or collapsed by default when querychat runs a query or updates the dashboard via the `querychat.tool_details` R option or the `QUERYCHAT_TOOL_DETAILS` environment variable. Valid values are `"expanded"`, `"collapsed"`, or `"default"`. (#137)
 
 * Added bookmarking support to `QueryChat$server()` and `querychat_app()`. When bookmarking is enabled (via `bookmark_store = "url"` or `"server"` in `querychat_app()` or `$app_obj()`, or via `enable_bookmarking = TRUE` in `$server()`), the chat state (including current query, title, and chat history) will be saved and restored with Shiny bookmarks. (#107)

pkg-r/R/DataSource.R

@@ -170,7 +170,7 @@ DataFrameSource <- R6::R6Class(
     #' @return A data frame with query results
     execute_query = function(query) {
       check_string(query, allow_null = TRUE, allow_empty = TRUE)
-      if (is.null(query) || query == "") {
+      if (is.null(query) || !nzchar(query)) {
         query <- paste0(
           "SELECT * FROM ",
           DBI::dbQuoteIdentifier(private$conn, self$table_name)
@@ -334,7 +334,7 @@ DBISource <- R6::R6Class(
     #' @return A data frame with query results
     execute_query = function(query) {
       check_string(query, allow_null = TRUE, allow_empty = TRUE)
-      if (is.null(query) || query == "") {
+      if (is.null(query) || !nzchar(query)) {
         query <- paste0(
           "SELECT * FROM ",
           DBI::dbQuoteIdentifier(private$conn, self$table_name)

pkg-r/R/QueryChat.R

@@ -333,7 +333,7 @@ QueryChat <- R6::R6Class(
         })
 
         shiny::observeEvent(input$reset_query, label = "on_reset_query", {
-          qc_vals$sql("")
+          qc_vals$sql(NULL)
           qc_vals$title(NULL)
         })
 

pkg-r/R/querychat_module.R

@@ -29,7 +29,7 @@ mod_server <- function(
 ) {
   shiny::moduleServer(id, function(input, output, session) {
     current_title <- shiny::reactiveVal(NULL, label = "current_title")
-    current_query <- shiny::reactiveVal("", label = "current_query")
+    current_query <- shiny::reactiveVal(NULL, label = "current_query")
     has_greeted <- shiny::reactiveVal(FALSE, label = "has_greeted")
     filtered_df <- shiny::reactive(label = "filtered_df", {
       data_source$execute_query(query = DBI::SQL(current_query()))
@@ -47,7 +47,7 @@ mod_server <- function(
     }
 
     reset_query <- function() {
-      current_query("")
+      current_query(NULL)
       current_title(NULL)
       querychat_tool_result(action = "reset")
     }

pkg-r/R/querychat_tools.R

@@ -159,7 +159,7 @@ querychat_tool_result <- function(
   action <- arg_match(action, c("update", "query", "reset"))
 
   if (action == "reset") {
-    query <- ""
+    query <- NULL
     title <- NULL
   }
 

pkg-r/inst/examples-shiny/02-sidebar-app/app.R

@@ -83,7 +83,7 @@ server <- function(input, output, session) {
   # Render the SQL query
   output$sql_query <- renderText({
     query <- qc_vals$sql()
-    if (query == "") {
+    if (is.null(query) || !nzchar(query)) {
       "No filter applied - showing all data"
     } else {
       query