You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: apps/docs/content/docs/api.mdx
-228Lines changed: 0 additions & 228 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -377,234 +377,6 @@ Compile a query to see the generated SQL without executing it. Useful for debugg
377
377
}`}
378
378
/>
379
379
380
-
## Custom SQL API
381
-
382
-
<Callouttype="info">
383
-
**New Feature!** 🚀 Use `properties.X` syntax for easy JSON property extraction. Write `properties.browser_name` instead of `JSONExtractString(properties, 'browser_name')`. Supports type annotations like `properties.user_id:int`, `properties.is_active:bool`.
384
-
</Callout>
385
-
386
-
### Execute Custom SQL Queries
387
-
388
-
Execute custom SQL queries directly against your ClickHouse analytics database with enterprise-grade security.
389
-
390
-
<CodeBlock
391
-
language="http"
392
-
code="POST /v1/custom-sql/execute"
393
-
/>
394
-
395
-
**Authentication:**
396
-
- Requires API key with `write:custom-sql` or `read:analytics` scope
397
-
- API key must have `read:data` access to the specified `clientId`
398
-
399
-
**Request:**
400
-
401
-
<CodeBlock
402
-
language="json"
403
-
code={`{
404
-
"query": "SELECT count() as events FROM analytics.events WHERE time >= now() - INTERVAL 7 DAY",
405
-
"clientId": "your-client-id",
406
-
"parameters": {
407
-
"customParam": "value"
408
-
}
409
-
}`}
410
-
/>
411
-
412
-
**Example with Properties.X Syntax:**
413
-
414
-
<CodeBlock
415
-
language="json"
416
-
code={`{
417
-
"query": "SELECT properties.browser_name AS browser_name, properties.user_id:int AS user_id, count() as events FROM analytics.custom_events WHERE properties.browser_name IS NOT NULL GROUP BY properties.browser_name, properties.user_id:int ORDER BY events DESC LIMIT 10",
418
-
"clientId": "your-client-id"
419
-
}`}
420
-
/>
421
-
422
-
**Headers:**
423
-
424
-
<CodeBlock
425
-
language="bash"
426
-
code={`curl -X POST https://api.databuddy.cc/v1/custom-sql/execute \\
427
-
-H "Content-Type: application/json" \\
428
-
-H "x-api-key: dbdy_your_api_key_here" \\
429
-
-d '{"query": "SELECT count() FROM analytics.events", "clientId": "client_123"}'`}
430
-
/>
431
-
432
-
**Available Tables:**
433
-
-`analytics.events` - All tracked events and page views
434
-
-`analytics.errors` - JavaScript errors and exceptions
435
-
-`analytics.custom_events` - Custom event tracking data
436
-
-`analytics.web_vitals` - Core Web Vitals performance metrics
437
-
438
-
**Properties.X Syntax Helper:**
439
-
Databuddy provides a convenient syntax helper that automatically converts `properties.X` notation to ClickHouse `JSONExtract` functions:
440
-
441
-
```sql
442
-
-- Instead of writing:
443
-
SELECT JSONExtractString(properties, 'browser_name') AS browser_name FROManalytics.events
**Important:** Always use `AS` aliases when selecting properties to get clean column names in your response. Without aliases, you'll get ugly column names like `"JSONExtractString(properties, 'browser_name')"` instead of `"browser_name"`.
Get example queries to help you get started with custom SQL.
547
-
548
-
<CodeBlock
549
-
language="http"
550
-
code="GET /v1/custom-sql/examples"
551
-
/>
552
-
553
-
**Response:**
554
-
555
-
<CodeBlock
556
-
language="json"
557
-
code={`{
558
-
"success": true,
559
-
"examples": [
560
-
{
561
-
"name": "Monthly Events Count",
562
-
"description": "Get monthly event counts for your client",
563
-
"query": "SELECT toStartOfMonth(time) as month_start, count() as event_count FROM analytics.events WHERE time >= now() - INTERVAL 6 MONTH GROUP BY month_start ORDER BY month_start DESC"
564
-
},
565
-
{
566
-
"name": "Top Pages by Views",
567
-
"description": "Get most popular pages",
568
-
"query": "SELECT path, count() as page_views, uniq(session_id) as unique_sessions FROM analytics.events WHERE time >= now() - INTERVAL 30 DAY AND event_name = 'page_view' GROUP BY path ORDER BY page_views DESC LIMIT 10"
"description": "Analyze browser usage using properties.X syntax",
573
-
"query": "SELECT properties.browser_name, count() as events, uniq(anonymous_id) as unique_users FROM analytics.events WHERE time >= now() - INTERVAL 7 DAY AND properties.browser_name IS NOT NULL GROUP BY properties.browser_name ORDER BY events DESC"
574
-
},
575
-
{
576
-
"name": "User Analytics with Typed Properties",
577
-
"description": "Analyze user behavior with typed property extraction",
578
-
"query": "SELECT properties.user_id:int as user_id, properties.is_premium:bool as is_premium, properties.session_duration:float as session_duration, count() as total_events FROM analytics.events WHERE time >= now() - INTERVAL 30 DAY AND properties.user_id:int IS NOT NULL GROUP BY properties.user_id:int, properties.is_premium:bool, properties.session_duration:float ORDER BY total_events DESC LIMIT 20"
579
-
},
580
-
{
581
-
"name": "Error Events Analysis",
582
-
"description": "Analyze error events",
583
-
"query": "SELECT url, count() as error_count FROM analytics.errors WHERE time >= now() - INTERVAL 7 DAY GROUP BY url ORDER BY error_count DESC LIMIT 10"
584
-
}
585
-
]
586
-
}`}
587
-
/>
588
-
589
-
**Error Responses:**
590
-
591
-
<CodeBlock
592
-
language="json"
593
-
code={`{
594
-
"success": false,
595
-
"error": "API key does not have access to client ID: client_123",
596
-
"code": "CLIENT_ACCESS_DENIED"
597
-
}`}
598
-
/>
599
-
600
-
**Common Error Codes:**
601
-
-`AUTH_REQUIRED` - API key missing or invalid
602
-
-`INSUFFICIENT_SCOPE` - API key lacks required scopes
603
-
-`CLIENT_ACCESS_DENIED` - No access to specified clientId
0 commit comments