From d681effa03fd25c6c4ed2236ff41e78d5b9930a1 Mon Sep 17 00:00:00 2001
From: TzeYiing <ty@tzeyiing.com>
Date: Fri, 26 Apr 2024 14:23:00 +0800
Subject: [PATCH] docs: api for querying logflare

---
 .../docs/concepts/endpoints.md                |  2 +-
 .../docs/concepts/querying.md                 | 35 +++++++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs.logflare.com/docs/concepts/querying.md

diff --git a/docs/docs.logflare.com/docs/concepts/endpoints.md b/docs/docs.logflare.com/docs/concepts/endpoints.md
index 26a00fdb4..1ae0d8229 100644
--- a/docs/docs.logflare.com/docs/concepts/endpoints.md
+++ b/docs/docs.logflare.com/docs/concepts/endpoints.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Endpoints
diff --git a/docs/docs.logflare.com/docs/concepts/querying.md b/docs/docs.logflare.com/docs/concepts/querying.md
new file mode 100644
index 000000000..583451d84
--- /dev/null
+++ b/docs/docs.logflare.com/docs/concepts/querying.md
@@ -0,0 +1,35 @@
+---
+sidebar_position: 4
+---
+
+# Querying
+
+To run adhoc queries for exploratory analysis, use the Querying or Search functionality. The use case for this differs from other features that Logflare offers:
+
+- For periodic query-based checks and data push integrations, use the Alerting functionality.
+- For building GET APIs for downstream programmatic consumption and data pull integrations, use the Endpoints functionality
+
+## Via Management API
+
+Sources can be queried through SQL using our management API.
+
+The following query parameters are available:
+
+- `?sql=` (string): accepts a BQ SQL query, alias for `?bq_sql=`.
+- `?bq_sql=` (string): accepts a BigQuery SQL query.
+- `?pg_sql=` (string): accepts a Postgres SQL query, for running on PostgreSQL backends. The first PostgreSQL backend will be selected.
+
+```
+# Endpoint
+GET https://api.logflare.app/api/query?sql=...
+
+# With a query
+GET https://api.logflare.app/api/query?bq_sql=select id, event_message, datetime(timestamp) as timestamp from `my_source` where timestamp > '2024-01-01'
+```
+
+## Caveats and Limitations
+
+The following caveats apply when querying this management API route:
+
+- Due to the partitioning that Logflare performs, queries must have a `WHERE` filter over the `timestamp` field at all times.
+- A hard maximum of 1000 rows will be returned for the BigQuery backend.