Skip to content

A platform for community discussion. Free, open, simple.

FEATURE: Add query examples for Data Explorer AI (#41288)

Natalie Tay5fd5946b1c1b
diff --git a/plugins/discourse-data-explorer/config/locales/server.en.yml b/plugins/discourse-data-explorer/config/locales/server.en.yml
index 40b3d3cb432..572073fd413 100644
--- a/plugins/discourse-data-explorer/config/locales/server.en.yml
+++ b/plugins/discourse-data-explorer/config/locales/server.en.yml
@@ -9,12 +9,15 @@ en:
name: "Data Explorer Query Generator"
description: "Generates SQL queries for Data Explorer from natural language"
tool_help:
+ find_queries: "Finds existing Data Explorer queries that may be useful examples"
run_sql: "Runs a SQL query and returns results"
submit_query: "Submits the final generated query"
tool_summary:
+ find_queries: "Finding example queries"
run_sql: "Running SQL query"
submit_query: "Submitting generated query"
tool_description:
+ find_queries: "Found example queries for %{search}"
run_sql: "Ran SQL query"
submit_query: "Submitted generated query %{name}"
discourse_data_explorer:
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/ai_query_generator.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/ai_query_generator.rb
index 55dfe9e6e15..2af58c6e08b 100644
--- a/plugins/discourse-data-explorer/lib/discourse_data_explorer/ai_query_generator.rb
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/ai_query_generator.rb
@@ -9,6 +9,7 @@ module DiscourseDataExplorer
def tools
[
DiscourseAi::Agents::Tools::DbSchema,
+ DiscourseDataExplorer::Tools::FindQueries,
DiscourseDataExplorer::Tools::RunSql,
DiscourseDataExplorer::Tools::SubmitQuery,
]
@@ -30,13 +31,29 @@ module DiscourseDataExplorer
<<~PROMPT
You are a PostgreSQL expert that generates queries for Discourse Data Explorer.
+ ## Request interpretation
+ Technical prompts may name specific tables, columns, params, joins, filters, or output columns. Treat these as schema-aware requests and preserve explicit requirements unless they conflict with Data Explorer rules.
+
+ Non-technical prompts may ask in community or business language, such as reports, updates, health checks, activity, or engagement. Treat these as requests for useful community-level insight, not just literal keyword matches. Prefer aggregate metrics over listing individual users. Produce a per-user leaderboard only when the user asks for top users, a list of members, shoutouts, or individual people.
+
+ Choose metrics that match the requested activity. For discussion participation, replies and distinct contributors are usually stronger signals than topics created, likes, or reading time. Do not add unrelated activity types unless the prompt asks for a broad activity mix.
+
+ Treat community-member populations as non-staff, non-staged, non-system users unless the prompt explicitly asks to include staff, staged users, or system users. Signup, registration, and member-count queries MUST include a staged-user filter such as `u.staged IS FALSE` unless the prompt explicitly asks to include staged users. For user population reports, exclude system users by default. Do not create staff-vs-member comparisons unless the user asks for a comparison.
+
+ For reports, updates, health, activity, and engagement questions, use a time trend when the user is asking how things are going or changing. If a trend is appropriate and the user does not specify a time grain, group by month. If the user does not specify a date range, add date params with useful recent defaults, such as the last 6 months.
+
+ For public activity based on posts or topics, include `posts`, `topics`, `users`, and `categories` in schema lookup. Join through topics and categories so deleted topics, PMs, and restricted categories can be excluded. For public activity metrics, filter categories with `c.read_restricted IS FALSE` unless the user explicitly asks for restricted categories.
+
## Workflow
- 1. Use the schema tool to look up relevant tables for the user's request
- 2. Write SQL based on the schema
- 3. Use RunSql to test the query
- 4. If RunSql returns an error, fix the SQL and test again
- 5. Repeat until the query runs successfully
- 6. Call submit_query with the final name, description, and verified SQL only after confirming the query works
+ 1. Classify the prompt as schema-aware or insight-oriented. Before choosing tables, decide the population, activity or outcome, and reporting grain.
+ 2. For non-trivial, community-oriented, or unfamiliar requests, use find_queries to look up existing Data Explorer queries that may be useful examples. Treat them as inspiration for SQL patterns, joins, params, and filters, not as authoritative answers to copy blindly.
+ 3. Use the schema tool to look up relevant tables for the request.
+ 4. Write SQL based on the request interpretation, relevant schema, and useful patterns from existing queries.
+ 5. Use RunSql to test the query.
+ 6. If RunSql returns an error, fix the SQL and test again. Repeat until the query runs successfully.
+ 7. After RunSql returns success, call submit_query next with the final name, description, and verified SQL. Do not call RunSql again with identical SQL.
+
+ When calling submit_query, use the exact SQL text from the final successful RunSql call, except removing a trailing semicolon if present. Include the `-- [params]` block and all parameter declaration comments if they were in the validated SQL. Do not add or remove LIMIT clauses, filters, params, aliases, comments, or formatting after validation.
Do not write the final query as plain text. Your final action must be a submit_query tool call with three fields:
- "name": a short descriptive name for the query (under 60 characters)
@@ -84,8 +101,9 @@ module DiscourseDataExplorer
- For category_id, group_id, user_id, user_list, post_id, topic_id, badge_id: OMIT the default value entirely (or use `null` prefix).
- Optional params: prefix the type with "null" and OMIT the default. The "null" prefix is the optional marker; do NOT use `= #null` as a default value (e.g. write `-- null category_id :category`, NOT `-- category_id :category = #null`).
- Date param defaults MUST be real ISO dates in YYYY-MM-DD form (today is #{Date.today.strftime("%Y-%m-%d")}). NEVER use natural-language defaults like "today", "yesterday", "3 months ago", or "14 jul 2015". For a date range, name params `:start_date` and `:end_date`.
- - Plural nouns → list-style param TYPES. Apply this rule independently to EACH plural noun in the prompt; don't skip one. Only `int_list`, `string_list`, `user_list`, `group_list` accept multiple values — single-value types like `category_id`, `user_id`, `topic_id` do NOT. Example: "Get topics for selected categories and tags." → `-- null int_list :category_ids` AND `-- null string_list :tag_names` (BOTH list types).
- - `ANY(:param)` and `:param IN (...)` REQUIRE :param to be a list-type (`int_list`, `string_list`, etc.). With single-value types (`category_id`, `user_id`, etc.), use `column = :param` instead. Mismatching the param type with array usage is a runtime error ("op ANY/ALL (array) requires array on right side").
+ - Plural nouns → list-style param TYPES. Apply this rule independently to EACH plural noun in the prompt; don't skip one. Only `int_list`, `string_list`, `user_list`, `group_list` accept multiple values — single-value types like `category_id`, `user_id`, `topic_id` do NOT. Plural "categories" MUST use `int_list :category_ids`, not `category_id :category`. Example: "Get topics for selected categories and tags." → `-- null int_list :category_ids` AND `-- null string_list :tag_names` (BOTH list types).
+ - For list-style params, use `column IN (:param)`. Do NOT use `ANY(:param)`; Data Explorer substitutes list params as comma-separated values, so `ANY(:param)` becomes invalid SQL. With single-value types (`category_id`, `user_id`, etc.), use `column = :param` instead.
+ - For optional list-style params, wrap only the param in parentheses for the null check: `((:param) IS NULL OR column IN (:param))`. The first `)` must come immediately after the param name. Examples: `((:category_ids) IS NULL OR t.category_id IN (:category_ids))` and `((:tag_names) IS NULL OR tags.name IN (:tag_names))`. Do NOT write `(:param IS NULL OR column IN (:param))` because the list expands to multiple SQL values.
- First-person prompts ("my posts", "queries about me", "topics I've replied to") MUST use `current_user_id` — this auto-injects the requester's user id at run time. Do NOT use `user_id :user = system` for "my" queries.
## Discourse domain knowledge
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/find_queries.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/find_queries.rb
new file mode 100644
index 00000000000..1495f42b73c
--- /dev/null
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/find_queries.rb
@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module DiscourseDataExplorer
+ module Tools
+ class FindQueries < DiscourseAi::Agents::Tools::Tool
+ DEFAULT_LIMIT = 5
+ MAX_LIMIT = 8
+ MAX_SEARCHABLE_QUERIES = 200
+ MAX_SQL_LENGTH = 2_000
+
+ def self.signature
+ {
+ name: name,
+ description:
+ "Finds existing Data Explorer queries that may be useful examples for the user's request. Use this for inspiration before writing SQL; do not copy results blindly.",
+ parameters: [
+ {
+ name: "search",
+ description:
+ "short search phrase describing the report or query pattern to find, for example: active members, tag usage, group replies",
+ type: "string",
+ required: true,
+ },
+ {
+ name: "limit",
+ description: "maximum number of example queries to return",
+ type: "integer",
+ required: false,
+ },
+ ],
+ }
+ end
+
+ def self.custom?
+ true
+ end
+
+ def self.name
+ "find_queries"
+ end
+
+ def invoke
+ if !context.user&.admin?
+ return error_response(I18n.t("discourse_data_explorer.errors.tool_not_allowed"))
+ end
+
+ search = parameters[:search].to_s.strip
+ limit = requested_limit
+ matches = matching_queries(search).first(limit)
+
+ {
+ search: search,
+ query_count: matches.length,
+ queries: matches.map { |query| serialize_query(query) },
+ note:
+ "Use these existing Data Explorer queries as examples for SQL patterns, joins, params, and filters. Still inspect schema and validate the final SQL with run_sql.",
+ }
+ end
+
+ protected
+
+ def description_args
+ { search: parameters[:search].to_s.truncate(100) }
+ end
+
+ private
+
+ def requested_limit
+ limit = parameters[:limit].presence&.to_i || DEFAULT_LIMIT
+ limit.clamp(1, MAX_LIMIT)
+ end
+
+ def matching_queries(search)
+ candidates = visible_saved_queries + unpersisted_default_queries
+ candidates.uniq!(&:id)
+
+ scored =
+ candidates.filter_map do |query|
+ score = score_query(query, search)
+ next if search.present? && score <= 0
+
+ [query, score]
+ end
+
+ scored
+ .sort_by { |query, score| [-score, query.last_run_at ? 0 : 1, query.name.to_s] }
+ .map(&:first)
+ end
+
+ def visible_saved_queries
+ DiscourseDataExplorer::Query
+ .where(hidden: false)
+ .order(Arel.sql("last_run_at DESC NULLS LAST"), updated_at: :desc)
+ .limit(MAX_SEARCHABLE_QUERIES)
+ .to_a
+ end
+
+ def unpersisted_default_queries
+ DiscourseDataExplorer::Query.unpersisted_defaults
+ end
+
+ def score_query(query, search)
+ return 1 if search.blank?
+
+ phrase = normalize(search)
+ terms = phrase.split.uniq
+ score = 0
+ fields = {
+ normalize(query.name) => 5,
+ normalize(query.description) => 3,
+ normalize(query.sql) => 1,
+ }
+
+ fields.each do |text, weight|
+ next if text.blank?
+
+ score += weight * 3 if text.include?(phrase)
+ terms.each { |term| score += weight if text.include?(term) }
+ end
+
+ score
+ end
+
+ def normalize(value)
+ value.to_s.downcase.gsub(/[^a-z0-9_]+/, " ").squish
+ end
+
+ def serialize_query(query)
+ {
+ id: query.id,
+ name: query.name,
+ description: query.description,
+ is_default: query.id.to_i < 0,
+ last_run_at: query.last_run_at&.iso8601,
+ params: query.params.map(&:to_hash),
+ sql: truncate_sql(query.sql),
+ }
+ end
+
+ def truncate_sql(sql)
+ return sql if sql.length <= MAX_SQL_LENGTH
+
+ "#{sql[0...MAX_SQL_LENGTH]}\n-- SQL truncated by find_queries"
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/run_sql.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/run_sql.rb
index ff189880e41..3d2773fdf72 100644
--- a/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/run_sql.rb
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/run_sql.rb
@@ -79,6 +79,8 @@ module DiscourseDataExplorer
rows: rows,
row_count: total_rows,
params_used: query_params,
+ next_action:
+ "Call submit_query with the exact same sql value after choosing a name and description. Do not call run_sql again with identical SQL.",
}
end
diff --git a/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/submit_query.rb b/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/submit_query.rb
index 36594b88886..5e01edd1fa1 100644
--- a/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/submit_query.rb
+++ b/plugins/discourse-data-explorer/lib/discourse_data_explorer/tools/submit_query.rb
@@ -26,7 +26,8 @@ module DiscourseDataExplorer
},
{
name: "sql",
- description: "the verified SQL query, without a trailing semicolon",
+ description:
+ "the exact SQL from the final successful run_sql call, including -- [params] comments, without a trailing semicolon",
type: "string",
required: true,
},
diff --git a/plugins/discourse-data-explorer/plugin.rb b/plugins/discourse-data-explorer/plugin.rb
index 2c6bf110c21..0d51639a40d 100644
--- a/plugins/discourse-data-explorer/plugin.rb
+++ b/plugins/discourse-data-explorer/plugin.rb
@@ -206,6 +206,7 @@ after_initialize do
if defined?(DiscourseAi)
require_relative "lib/discourse_data_explorer/ai_query_params"
+ require_relative "lib/discourse_data_explorer/tools/find_queries"
require_relative "lib/discourse_data_explorer/tools/run_sql"
require_relative "lib/discourse_data_explorer/tools/submit_query"
require_relative "lib/discourse_data_explorer/ai_query_generator"
diff --git a/plugins/discourse-data-explorer/spec/lib/ai_query_generator_spec.rb b/plugins/discourse-data-explorer/spec/lib/ai_query_generator_spec.rb
index 8ccc2b25915..06d1c981324 100644
--- a/plugins/discourse-data-explorer/spec/lib/ai_query_generator_spec.rb
+++ b/plugins/discourse-data-explorer/spec/lib/ai_query_generator_spec.rb
@@ -6,10 +6,65 @@ describe DiscourseDataExplorer::AiQueryGenerator do
expect(agent.tools).to include(
DiscourseAi::Agents::Tools::DbSchema,
+ DiscourseDataExplorer::Tools::FindQueries,
DiscourseDataExplorer::Tools::RunSql,
DiscourseDataExplorer::Tools::SubmitQuery,
)
expect(agent.response_format).to be_nil
expect(agent.system_prompt).to include("submit_query")
end
+
+ it "instructs the agent to submit the exact validated SQL" do
+ prompt = described_class.new.system_prompt
+
+ expect(prompt).to include("After RunSql returns success, call submit_query next")
+ expect(prompt).to include("Do not call RunSql again with identical SQL")
+ expect(prompt).to include("use the exact SQL text from the final successful RunSql call")
+ expect(prompt).to include("Include the `-- [params]` block")
+ expect(prompt).to include("Do not add or remove LIMIT clauses")
+ end
+
+ it "frames non-technical community prompts as aggregate insight" do
+ prompt = described_class.new.system_prompt
+
+ expect(prompt).to include("## Request interpretation")
+ expect(prompt).to include("Treat these as schema-aware requests")
+ expect(prompt).to include("preserve explicit requirements")
+ expect(prompt).to include("Non-technical prompts may ask in community or business language")
+ expect(prompt).to include("Prefer aggregate metrics over listing individual users")
+ expect(prompt).to include("replies and distinct contributors")
+ expect(prompt).to include("non-staff, non-staged, non-system users")
+ expect(prompt).to include("Signup, registration, and member-count queries MUST")
+ expect(prompt).to include("u.staged IS FALSE")
+ expect(prompt).to include("Do not create staff-vs-member comparisons")
+ expect(prompt).to include(
+ "If a trend is appropriate and the user does not specify a time grain",
+ )
+ expect(prompt).to include("Join through topics and categories")
+ expect(prompt).to include("c.read_restricted IS FALSE")
+ end
+
+ it "starts the workflow with request classification" do
+ prompt = described_class.new.system_prompt
+
+ expect(prompt).to include("1. Classify the prompt as schema-aware or insight-oriented")
+ expect(prompt).to include("decide the population, activity or outcome, and reporting grain")
+ expect(prompt).to include("use find_queries")
+ expect(prompt).to include("Treat them as inspiration")
+ expect(prompt).to include("3. Use the schema tool")
+ expect(prompt).to include(
+ "Write SQL based on the request interpretation, relevant schema, and useful patterns",
+ )
+ end
+
+ it "instructs list params to use Data Explorer IN syntax" do
+ prompt = described_class.new.system_prompt
+
+ expect(prompt).to include("column IN (:param)")
+ expect(prompt).to include("Do NOT use `ANY(:param)`")
+ expect(prompt).to include("Plural \"categories\" MUST use `int_list :category_ids`")
+ expect(prompt).to include("((:param) IS NULL OR column IN (:param))")
+ expect(prompt).to include("((:category_ids) IS NULL OR t.category_id IN (:category_ids))")
+ expect(prompt).to include("((:tag_names) IS NULL OR tags.name IN (:tag_names))")
+ end
end
diff --git a/plugins/discourse-data-explorer/spec/lib/tools/find_queries_spec.rb b/plugins/discourse-data-explorer/spec/lib/tools/find_queries_spec.rb
new file mode 100644
index 00000000000..36a9d68f260
--- /dev/null
+++ b/plugins/discourse-data-explorer/spec/lib/tools/find_queries_spec.rb
@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+describe DiscourseDataExplorer::Tools::FindQueries do
+ fab!(:llm_model)
+ fab!(:admin)
+ fab!(:user)
+
+ let(:bot_user) { DiscourseAi::AiBot::EntryPoint.find_user_from_model(llm_model.name) }
+ let(:llm) { DiscourseAi::Completions::Llm.proxy(llm_model) }
+
+ before do
+ SiteSetting.discourse_ai_enabled = true
+ SiteSetting.data_explorer_enabled = true
+ SiteSetting.ai_bot_enabled = true
+ end
+
+ def invoke_with(user:, search: "warehouse unicorn", limit: nil)
+ parameters = { search: search }
+ parameters[:limit] = limit if limit
+
+ described_class.new(
+ parameters,
+ bot_user: bot_user,
+ llm: llm,
+ context: DiscourseAi::Agents::BotContext.new(user: user),
+ ).invoke
+ end
+
+ it "returns matching visible queries with SQL for inspiration" do
+ query =
+ Fabricate(
+ :query,
+ name: "Warehouse Unicorn Activity",
+ description: "Shows warehouse unicorn activity by month",
+ sql: <<~SQL,
+ -- [params]
+ -- int :minimum_posts = 5
+
+ SELECT COUNT(*) AS post_count
+ FROM posts
+ HAVING COUNT(*) >= :minimum_posts
+ SQL
+ )
+
+ result = invoke_with(user: admin)
+
+ expect(result[:query_count]).to eq(1)
+ expect(result[:queries].first).to include(
+ id: query.id,
+ name: "Warehouse Unicorn Activity",
+ description: "Shows warehouse unicorn activity by month",
+ is_default: false,
+ )
+ expect(result[:queries].first[:sql]).to include("SELECT COUNT(*) AS post_count")
+ expect(result[:queries].first[:params]).to contain_exactly(
+ include(identifier: "minimum_posts", type: :int),
+ )
+ expect(result[:note]).to include("examples")
+ end
+
+ it "includes bundled default queries" do
+ result = invoke_with(user: admin, search: "user participation")
+
+ expect(result[:queries].map { |query| query[:id] }).to include(-8)
+ expect(result[:queries].find { |query| query[:id] == -8 }).to include(is_default: true)
+ end
+
+ it "omits hidden saved queries" do
+ Fabricate(
+ :query,
+ name: "Warehouse Unicorn Hidden",
+ description: "Should not be visible",
+ sql: "SELECT 1",
+ hidden: true,
+ )
+
+ result = invoke_with(user: admin)
+
+ expect(result[:queries]).to be_empty
+ end
+
+ it "blocks a non-admin caller" do
+ result = invoke_with(user: user)
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to eq(I18n.t("discourse_data_explorer.errors.tool_not_allowed"))
+ end
+end
diff --git a/plugins/discourse-data-explorer/spec/lib/tools/run_sql_spec.rb b/plugins/discourse-data-explorer/spec/lib/tools/run_sql_spec.rb
index b783049bfdc..6e3cb564423 100644
--- a/plugins/discourse-data-explorer/spec/lib/tools/run_sql_spec.rb
+++ b/plugins/discourse-data-explorer/spec/lib/tools/run_sql_spec.rb
@@ -30,6 +30,7 @@ describe DiscourseDataExplorer::Tools::RunSql do
expect(result[:status]).to eq("success")
expect(result[:columns]).to eq(["one"])
+ expect(result[:next_action]).to include("Call submit_query with the exact same sql value")
end
it "passes the current user when validating current_user_id params" do
diff --git a/plugins/discourse-data-explorer/spec/lib/tools/submit_query_spec.rb b/plugins/discourse-data-explorer/spec/lib/tools/submit_query_spec.rb
index ff539afd08f..ea04fe2ad0a 100644
--- a/plugins/discourse-data-explorer/spec/lib/tools/submit_query_spec.rb
+++ b/plugins/discourse-data-explorer/spec/lib/tools/submit_query_spec.rb
@@ -13,6 +13,13 @@ describe DiscourseDataExplorer::Tools::SubmitQuery do
SiteSetting.ai_bot_enabled = true
end
+ it "describes SQL as the exact validated query" do
+ sql_param = described_class.signature[:parameters].find { |param| param[:name] == "sql" }
+
+ expect(sql_param[:description]).to include("exact SQL from the final successful run_sql call")
+ expect(sql_param[:description]).to include("including -- [params] comments")
+ end
+
it "stores the generated query on the bot context and stops the tool chain" do
context.feature_context[described_class::VALIDATED_SQL_KEY] = "SELECT id AS user_id FROM users"