​

Analytics Troubleshooting

​

Getting Empty Results?

​

Time Range Issues

• Your workspace might be new with no verification data yet
• Try a shorter time range: WHERE time >= now() - INTERVAL 1 HOUR
• Verify your time filters are working: SELECT MAX(time) as latest FROM key_verifications_v1

​

Filter Problems

• Wrong key_space_id - Find your API ID in dashboard settings
• Empty external_id values - Filter them out: WHERE external_id != ''
• Case sensitivity - Check exact values: SELECT DISTINCT external_id FROM key_verifications_v1 LIMIT 10

​

Data Availability

• Analytics may have a few minutes delay
• Check recent data: SELECT COUNT(*) FROM key_verifications_v1 WHERE time >= now() - INTERVAL 1 HOUR

​

Queries Timing Out?

​

Use Aggregated Tables

-- Instead of raw table for long ranges:
-- Slow for 7+ days
SELECT COUNT(*) FROM key_verifications_v1 WHERE time >= now() - INTERVAL 7 DAY

-- Fast for 7+ days
SELECT SUM(count) FROM key_verifications_per_day_v1 WHERE time >= now() - INTERVAL 7 DAY

​

Add Time Filters First

-- Always filter by time early (uses indexes)
WHERE time >= now() - INTERVAL 7 DAY
  AND external_id = 'user_123'  -- Additional filters after time

​

Limit Result Size

-- Prevent large result sets
SELECT external_id, SUM(count) as usage
FROM key_verifications_per_day_v1
WHERE time >= now() - INTERVAL 30 DAY
GROUP BY external_id
ORDER BY usage DESC
LIMIT 100  -- Add LIMIT for large datasets

​

API Errors?

​

Missing Property ‘query’

// Wrong field name
{"sql": "SELECT COUNT(*) FROM key_verifications_v1"}

// Correct field name
{"query": "SELECT COUNT(*) FROM key_verifications_v1"}

​

Permission Denied

• Ensure your root key has api.*.read_analytics or api.<api_id>.read_analytics
• Check key is not expired or revoked
• Verify workspace ID matches your key’s permissions See forbidden for permission issues.

​

Invalid Function Error

• Check Query Restrictions for allowed functions
• Some ClickHouse functions are blocked for security
• Use alternative approaches from Quick Reference
• See invalid_analytics_function for details

​

Invalid Table Error

• Only analytics tables are accessible (no system.* or information_schema.*)
• Use table names from Schema Reference
• See invalid_analytics_table for details

​

Query Not Supported

• Only SELECT queries are allowed in analytics
• INSERT, UPDATE, DELETE, etc. are blocked
• See invalid_analytics_query_type for details

​

Performance Problems?

​

Choose Right Table

• < 1 hour: key_verifications_v1 (raw)
• < 24 hours: key_verifications_per_minute_v1
• < 30 days: key_verifications_per_hour_v1
• < 1 year: key_verifications_per_day_v1
• > 1 year: key_verifications_per_month_v1

​

Filter Before Grouping

-- Less efficient
SELECT external_id, SUM(count) as usage
FROM key_verifications_per_day_v1
GROUP BY external_id
HAVING SUM(count) > 1000

-- More efficient
SELECT external_id, SUM(count) as usage
FROM key_verifications_per_day_v1
WHERE time >= now() - INTERVAL 30 DAY  -- Filter first
GROUP BY external_id
HAVING SUM(count) > 1000

​

Avoid SELECT *

• Only select columns you need
• Reduces memory usage and network transfer