Skip to main content

Overview

The query-db command provides tools for querying the TikTok Miner PostgreSQL database. It supports raw SQL queries for direct database access.
The CLI implementation is currently in development. The command structure described here reflects the planned interface. Some commands may reference legacy fields from the codebase evolution.

Command Syntax

tiktok-miner query-db [sql] [options]

Arguments

  • [sql] - Raw SQL query to execute directly against the database

Options

The query-db command accepts various options for structured queries:
  • -u, --username <username> - Filter by username
  • -r, --repo <repo> - Repository or profile identifier
  • -j, --jd <id> - Job description or category ID
  • -t, --tag <tag> - Filter by tag
  • -l, --limit <number> - Limit number of results
  • --repos - Include additional profile data
  • --contributions - Include contribution metrics
  • --contributors - Include contributor information

Database Schema

The TikTok Miner database uses PostgreSQL with Prisma ORM. Key tables include:

Creator Profiles

-- Main creator profile table
SELECT * FROM "CreatorProfile" 
WHERE name LIKE '%TechGuru%' 
LIMIT 10;

Platform Metrics

-- TikTok metrics for a creator
SELECT * FROM "TiktokMetrics" 
WHERE username = 'techguru';

-- Instagram metrics
SELECT * FROM "InstagramMetrics"
WHERE username = 'techguru';

Time-Series Data

-- Historical metrics over time
SELECT * FROM "CreatorMetricsHistory"
WHERE "creatorProfileId" = '<creator-id>'
ORDER BY timestamp DESC
LIMIT 30;

Usage Examples

Raw SQL Query

Execute a direct SQL query against the database:
tiktok-miner query-db "SELECT id, name, platform FROM \"CreatorProfile\" LIMIT 10"

Query TikTok Profiles

tiktok-miner query-db "SELECT username, \"followerCount\", \"engagementRate\" FROM \"TiktokProfile\" ORDER BY \"followerCount\" DESC LIMIT 20"

Get Engagement Analytics

tiktok-miner query-db "SELECT \"creatorProfileId\", \"hourlyLikes\", \"hourlyComments\", \"peakEngagementHour\" FROM \"EngagementAnalytics\" WHERE timestamp > NOW() - INTERVAL '7 days'"

Budget and Cost Tracking

tiktok-miner query-db "SELECT platform, \"costAmount\", \"costDate\" FROM \"CostAllocation\" WHERE \"costDate\" > NOW() - INTERVAL '30 days' ORDER BY \"costDate\" DESC"

Common Queries

Top Creators by Engagement

SELECT 
  cp.name,
  cp."totalReach",
  cp."averageEngagementRate",
  cp."compositeEngagementScore"
FROM "CreatorProfile" cp
WHERE cp."averageEngagementRate" > 5.0
ORDER BY cp."compositeEngagementScore" DESC
LIMIT 20;

Platform Distribution

SELECT 
  platform,
  COUNT(*) as creator_count,
  AVG("followerCount") as avg_followers
FROM "CreatorProfile"
GROUP BY platform;

Recent Discoveries

SELECT 
  name,
  platform,
  "totalReach",
  "createdAt"
FROM "CreatorProfile"
WHERE "createdAt" > NOW() - INTERVAL '7 days'
ORDER BY "createdAt" DESC;

Budget Status

SELECT 
  name,
  "budgetType",
  "totalAmount",
  "spentAmount",
  "remainingAmount",
  status
FROM "Budget"
WHERE status = 'ACTIVE';

Output Formats

The CLI supports different output formats for query results:
  • Table (default): Pretty-printed table with borders
  • JSON: Machine-readable JSON output
  • CSV: Comma-separated values for spreadsheets

Database Schema Reference

For complete schema documentation, see the Database Setup page which includes:
  • Full Prisma schema
  • Table relationships
  • Index definitions
  • TimescaleDB hypertables

Database Setup

Complete database schema and setup guide

API Monitoring

Monitor database queries and performance

Troubleshooting

Ensure your DATABASE_URL environment variable is correctly set and the PostgreSQL server is running.
# Check database connection
docker-compose ps postgres
The database user needs appropriate permissions. Check the user has SELECT, INSERT, UPDATE permissions on the required tables.
For large datasets, consider adding a LIMIT clause or creating appropriate indexes. See the database setup guide for performance optimization tips.

Build docs developers (and LLMs) love