Analytics Troubleshooting#

Getting Empty Results?#

Check these common causes:

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?#

Try these optimizations:

Use Aggregated Tables#

-- Instead of raw table for long ranges:-- Slow for 7+ daysSELECT COUNT(*) FROM key_verifications_v1 WHERE time >= now() - INTERVAL 7 DAY-- Fast for 7+ daysSELECT 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 setsSELECT external_id, SUM(count) as usageFROM key_verifications_per_day_v1WHERE time >= now() - INTERVAL 30 DAYGROUP BY external_idORDER BY usage DESCLIMIT 100  -- Add LIMIT for large datasets

API Errors?#

Common fixes:

Missing Property 'query'#

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

See invalid_input error for API request format issues.

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 the forbidden error 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 error 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 error for details

Query Not Supported#

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

Performance Problems?#

Optimization tips:

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 efficientSELECT external_id, SUM(count) as usageFROM key_verifications_per_day_v1GROUP BY external_idHAVING SUM(count) > 1000-- More efficientSELECT external_id, SUM(count) as usageFROM key_verifications_per_day_v1WHERE time >= now() - INTERVAL 30 DAY  -- Filter firstGROUP BY external_idHAVING SUM(count) > 1000

Avoid SELECT *#

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