Run Data Explorer queries with the Discourse API

Discourse · 2019 年 6 月 11 日午後 7:43

This guide explains how to use the Discourse API to create, run, and manage queries with the Data Explorer plugin.

Required user level: Administrator

Virtually any action that can be performed through the Discourse user interface can also be triggered with the Discourse API.

This document provides a comprehensive overview for utilizing the API specifically in conjunction with the Data Explorer plugin.

For a general overview of how to find the correct API request for an action, see: Reverse engineer the Discourse API.

Running a Data Explorer query

To run a Data Explorer query via the API, make a POST request to /admin/plugins/explorer/queries/<query-id>/run. You can find the query ID by visiting it through your Discourse site and checking the id parameter in the address bar.

Below is an example query with an ID of 20 that returns topics by views on a specified date:

--[params]
-- date :viewed_at

SELECT
topic_id,
COUNT(1) AS views_for_date
FROM topic_views
WHERE viewed_at = :viewed_at
GROUP BY topic_id
ORDER BY views_for_date DESC

This query can be run from a terminal with:

curl -X POST "https://your-site-url/admin/plugins/explorer/queries/20/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"viewed_at":"2019-06-10"}'

Note that you’ll need to replace the <api-key>, <your-site-url> with your API key and domain.

Creating a query via the API

To create a Data Explorer query via the API, you’ll need to make a POST request to /admin/plugins/explorer/queries.

You will also need to specify the query name and sql to use for the new query in the API call.

Below is an example of how to create a new query using the API:

curl -X POST "https://your-site-url/admin/plugins/explorer/queries" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: <username>" \
-F 'query[name]=Example Query' \
-F 'query[sql]=SELECT COUNT(*) FROM users'

This API call will return a response like:

{"query":{"id":49,"name":"Example Query","description":null,"username":"<username>","group_ids":[],"last_run_at":null,"user_id":1,"sql":"SELECT COUNT(*) FROM users","param_info":[],"created_at":"2025-03-13T18:41:44.226Z","hidden":false}}%

You can then run the query by using the query ID from the response (in this case, 49 ).

Returned results will be structured within the rows field.

Handling large datasets

The Data Explorer plugin limits results to 1000 rows by default. To paginate through larger datasets, you can use the example query below:

--[params]
-- integer :limit = 100
-- integer :page = 0
SELECT * 
FROM generate_series(1, 10000)
OFFSET :page * :limit 
LIMIT :limit

To fetch the results page-by-page, increment the page parameter in the request:

curl -X POST "https://your-site-url/admin/plugins/explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}'

Stop when result_count is zero.

For additional information about handling large datasets, see: Result Limits and Exporting Queries

Removing `relations` data from the results

When Data Explorer queries are run through the user interface, a relations object is added to the results. This data is used for rendering the user in UI results, but you are unlikely to need it when running queries via the API.

To remove that data from the results, add a download=true parameter with your request:

curl -X POST "https://your-site-url/admin/plugins/explorer/queries/27/run" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: <api-key>" \
-H "Api-Username: system" \
-F 'params={"page":"0"}' \
-F "download=true"

API authentication

Details about generating an API key for the requests can be found here: Create and configure an API key.

If the API key is only going to be used to run Data Explorer queries, you can select “Granular” from the Scope drop down menu, then select the “run queries” scope.

FAQs

Is there any api endpoint I can use to get the list of reports and the ID numbers? I want to build a dropdown with the list in it?

Yes, you can make an authenticated GET request to /admin/plugins/explorer/queries.json to get a list of all queries on the site.

Is it possible to send parameters with the post request?

Yes, include SQL parameters using the -F option, as shown in the examples.

Is CSV export for queries supported by the API?

While JSON output is standard, you can manually convert results to CSV. Native CSV export is no longer supported.

Additional resources

37Rb · 2024 年 5 月 10 日午前 2:47

このコメントは、APIからCSVエクスポートができることを示唆しているようです。それは可能ですか？CSVとしてデータが必要なので、単に興味があります。JSONとして取得してCSVに変換することは常にできますが、CSVを取得する組み込みの方法があれば、もう少し簡単になります。

francis_exalate · 2025 年 1 月 4 日午後 1:50

「過去50秒間に作成または更新された」というクエリを実行することは可能ですか？

Canapin · 2025 年 1 月 4 日午後 2:21

AI says

-- [params]
-- int :seconds = 50

SELECT
    p.id AS post_id,
    p.created_at,
    p.updated_at,
    p.raw AS post_content,
    p.user_id,
    t.title AS topic_title,
    t.id AS topic_id
FROM posts p
INNER JOIN topics t ON t.id = p.topic_id
WHERE
    (EXTRACT(EPOCH FROM (NOW() - p.created_at)) <= :seconds
    OR EXTRACT(EPOCH FROM (NOW() - p.updated_at)) <= :seconds)
    AND p.deleted_at IS NULL
    AND t.deleted_at IS NULL
ORDER BY p.created_at DESC
LIMIT 50

簡単なテストをしたところ、動作するようです

Moin · 2025 年 1 月 4 日午後 2:34

投稿に追加した「いいね」が表示されません。

post_actions を使用する必要があると思います。

--[params]
--string :timespan = 50 seconds

SELECT post_id,
       user_id,
       created_at,
       updated_at,
       deleted_at
FROM  post_actions
WHERE post_action_type_id=2 AND updated_at > NOW() - INTERVAL :timespan

より見栄えの良い結果が得られるバージョン

--[params]
--string :timespan = 50 seconds
--boolean :include_in_timespan_deleted = false

SELECT
  post_id,
  user_id,
  CASE
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - created_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400), ' days ago')
  END AS relative_created_at,
  CASE
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - updated_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - updated_at)) / 86400), ' days ago')
  END AS relative_updated_at,
  CASE
    WHEN deleted_at IS NULL THEN 'no'
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 60 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at))), ' seconds ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 3600 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 60), ' minutes ago')
    WHEN EXTRACT(EPOCH FROM (NOW() - deleted_at)) < 86400 THEN CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 3600), ' hours ago')
    ELSE CONCAT(ROUND(EXTRACT(EPOCH FROM (NOW() - deleted_at)) / 86400), ' days ago')
  END AS relative_deleted_at
FROM
  post_actions
WHERE
  post_action_type_id = 2
  AND updated_at > NOW() - INTERVAL :timespan
  AND (
    :include_in_timespan_deleted = false
    OR (deleted_at IS NOT NULL AND deleted_at > NOW() - INTERVAL :timespan)
  )

Canapin · 2025 年 1 月 4 日午後 3:37

ああ、読み間違えました！「作成または更新された最後の50秒」のようなクエリを実行できますか？

（一重引用符の位置に注意してください）

francis_exalate · 2025 年 1 月 4 日午後 6:58

皆さん、ありがとうございます。

ask.discourse が私をここに誘導したので、ここに投稿しました。
API がこの機能を提供しているかどうかを知りたいのです。

Canapin · 2025 年 1 月 4 日午後 7:09

はい、もちろんです。

データエクスプローラーでクエリを作成し、このガイドで説明されているようにAPI経由でクエリを実行します。

MoinのクエリをAPI経由で実行したところ、期待どおりの結果が正しく返されました。

tanya_byrne · 2025 年 1 月 14 日午後 10:57

私もこれについて疑問に思っていました。API経由でデータをエクスポートする方法はJSONだけですか、それともData ExplorerではCSVエクスポートもサポートされていますか？

francis_exalate · 2025 年 1 月 19 日午後 11:18

皆さん、ありがとうございます。

返信が遅くなり申し訳ありません。少しの間オフラインでした。

現在行っているのは、今日作成されたすべてのトピック/投稿を検索し、タイムスタンプより前に更新されたトピック/投稿を除外することです。

Canapin · 2025 年 1 月 19 日午後 11:35

自分でやりたくない場合は、ask.discourse.com のボットに尋ねることができます。通常、Discourse 関連の SQL クエリに関してはかなり正確です（ただし、正しいと仮定せずに、コードを確認して確実にしてください）。

srinivas.chilukuri · 2025 年 5 月 6 日午後 4:06

Content-Type ヘッダーは正しいですか？
開発者ツールで、パラメータ付きのData Explorerクエリを検査すると、Content-Type ヘッダーは次のように表示されます。

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

しかし、現在の cURL コマンドには次が含まれています。

-H "Content-Type: multipart/form-data;"

blake · 2025 年 5 月 6 日午後 4:30

multipart/form-data
application/x-www-form-urlencoded
application/json

は、APIリクエストを行う際に使用できる有効なコンテンツタイプです。

srinivas.chilukuri · 2025 年 5 月 6 日午後 4:37

@blake
language python
library requests
APIサンプルData Explorerクエリを、3つのパラメータを含めて提供していただけますか？
パラメータは、paramsを厳密に二重引用符で囲む必要があると記載されているTopicを参照してください。

blake · 2025 年 5 月 6 日午後 5:15

はい、Python を使用した例を次に示します。

import json
import requests

API_KEY      = "YOUR_API_KEY"
API_USERNAME = "system"
QUERY_ID     = 20
SITE_URL     = "https://your-site-url"

# すべての値は文字列である必要があります
params = {
    "user_id":   "2",
    "viewed_at": "2019-06-10",
    "limit":     "5"
}

# Data Explorer は params を JSON エンコードされた文字列として期待します
payload = {
    "params": json.dumps(params)
}

url = f"{SITE_URL}/admin/plugins/explorer/queries/{QUERY_ID}/run"
headers = {
    "Api-Key":       API_KEY,
    "Api-Username":  API_USERNAME,
    "Content-Type":  "application/json"
}

r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()
print(r.json())

トピック		返信	表示
Discourse Data Explorer Plugin official , data-explorer , included-in-core	31	80322	2025 年 10 月 22 日
Discourse AI + Data Explorer? Feature ai , data-explorer , ai-bot , completed	49	3585	2024 年 1 月 13 日
Data Explorer Tutorial - Part 1 - Writing Your First Query Data & reporting data-explorer , sql-tutorial	0	1415	2023 年 9 月 5 日
How to create a data explorer query with the APIs? Dev data-explorer , rest-api	6	800	2023 年 11 月 9 日
Download result of queries into Google Spreadsheet Data & reporting sql-query	10	3576	2020 年 9 月 30 日