openpodcast · woolfg · Oct 13, 2025 · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025
diff --git a/Makefile b/Makefile
@@ -8,13 +8,17 @@ help: ## help message, list all command
 .PHONY: up docker-run
 up docker-run: docker-build ## docker-compose up
 	touch dbinit.sql
-	docker compose up --build
+	docker compose -d up --build
 
 .PHONY: up-db
 up-db: ## docker-compose up db
 	touch dbinit.sql
 	docker compose up db
 
+.PHONY: logs
+logs: ## docker-compose logs -f
+	docker compose logs -f
+
 .PHONY: down-db
 down-db: ## docker-compose down db and remove volumes
 	docker compose down -v 

diff --git a/db_schema/queries/v1/appleEpisodesLTR.sql b/db_schema/queries/v1/appleEpisodesLTR.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Apple Podcasts episode listener-through-rate (LTR) data showing retention at 25%, 50%, 75%, and 100% completion points.
+-- Fields: Episode Name, GUID, Date, Quarter 1-4 LTR percentages, Apple Listeners count
+
 WITH
 apple as (
   SELECT 

diff --git a/db_schema/queries/v1/appleEpisodesPlays.sql b/db_schema/queries/v1/appleEpisodesPlays.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Apple Podcasts episode performance metrics including plays, listening time, and engagement data.
+-- Fields: Date, Episode Name, GUID, Plays Count, Total Time Listened, Unique Engaged Listeners, Unique Listeners
+
 WITH
 apple as (
   SELECT 

diff --git a/db_schema/queries/v1/applePodcastFollowers.sql b/db_schema/queries/v1/applePodcastFollowers.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Apple Podcasts follower metrics showing daily follower growth and churn.
+-- Fields: Date, Total Followers, Total Unfollowers, Gained Followers, Lost Followers
+
 SELECT 
   atf_date as `date`,
   atf_totalfollowers as total_followers,

diff --git a/db_schema/queries/v1/chartsRankings.sql b/db_schema/queries/v1/chartsRankings.sql
@@ -1,5 +1,6 @@
--- Chart rankings query using provider IDs from podcasts table
--- Requires @account_id parameter to be set
+-- @doc
+-- Returns podcast and episode chart rankings from Spotify and Apple Podcasts across different markets and categories.
+-- Fields: Platform, Item Type, Show ID, Episode ID, Episode Name, Market, Chart Name, Position, Chart Date
 
 WITH podcast_ids AS (
   SELECT 

diff --git a/db_schema/queries/v1/episodesAge.sql b/db_schema/queries/v1/episodesAge.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Spotify episode listener demographics by age group with listener counts and percentages.
+-- Fields: Date, Episode GUID, Age Group, Listeners Count, Percentage of Total
+
 WITH data as
 (
   SELECT spa_date,episode_id,spa_facet,spa_gender_female+spa_gender_male+spa_gender_non_binary+spa_gender_not_specified as listeners

diff --git a/db_schema/queries/v1/episodesDailyMetrics.sql b/db_schema/queries/v1/episodesDailyMetrics.sql
@@ -1,5 +1,6 @@
--- Daily episodes metrics from Apple and Spotify platforms using episodeMapping view
--- Returns daily performance metrics for plays, listeners, streams, and engagement data
+-- @doc
+-- Returns daily performance metrics for plays, listeners, streams, and engagement data of episodes from Apple and Spotify.
+-- Fields: Podcast ID, Spotify Episode ID, Apple Episode ID, GUID, Date, Spotify Starts, Spotify Streams, Spotify Listeners, Apple Plays, Apple Unique Listeners, Apple Engaged Listeners, Apple Total Time Listened
 
 SELECT 
     -- Episode identifiers from mapping view

diff --git a/db_schema/queries/v1/episodesGender.sql b/db_schema/queries/v1/episodesGender.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Spotify episode listener demographics broken down by gender and age group.
+-- Fields: Date, Episode GUID, Gender, Listeners Count, Age Group
+
 WITH data as
 (
     SELECT spa_date,ep_guid,spa_facet,spa_gender_female,spa_gender_male,spa_gender_non_binary,spa_gender_not_specified

diff --git a/db_schema/queries/v1/episodesLTR.sql b/db_schema/queries/v1/episodesLTR.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns combined episode listener-through-rate (LTR) data from both Spotify and Apple Podcasts showing retention at different completion points.
+-- Fields: Episode Name, GUID, Date, Combined Quarter 1-4 LTR, Individual Platform LTR values, Listener Counts
+
 WITH
 spotify as (
   SELECT 

diff --git a/db_schema/queries/v1/episodesLTRHistogram.sql b/db_schema/queries/v1/episodesLTRHistogram.sql
@@ -1,4 +1,8 @@
 
+-- @doc
+-- Returns detailed listener retention histogram data for episodes from both Spotify and Apple Podcasts at 15-second intervals.
+-- Fields: Episode GUID, Date, Max Listeners (Spotify/Apple), Histogram Data Arrays
+
 WITH spotify as (
   SELECT JSON_ARRAYAGG(JSON_OBJECT(sample_id-1,listeners)) as histogram,episode_id,account_id,spp_date,spp_sample_max FROM 
     spotifyEpisodePerformance CROSS JOIN

diff --git a/db_schema/queries/v1/episodesMetadata.sql b/db_schema/queries/v1/episodesMetadata.sql
@@ -1,5 +1,6 @@
--- Combined episodes metadata from Apple and Spotify platforms using episodeMapping view
--- Returns metadata for all episodes with their basic information
+-- @doc
+-- Returns comprehensive episode metadata from both Spotify and Apple Podcasts including URLs, descriptions, release dates, and technical details.
+-- Fields: Account ID, Episode IDs, Name, GUID, URLs, Release Dates, Descriptions, Duration, Language, Content Flags
 
 SELECT 
     -- Common episode identifiers from mapping view

diff --git a/db_schema/queries/v1/episodesTotalMetrics.sql b/db_schema/queries/v1/episodesTotalMetrics.sql
@@ -1,6 +1,10 @@
 -- Total episodes metrics from Apple and Spotify platforms using episodeMapping view
 -- Returns cumulative/total performance metrics for plays, listeners, and engagement data
 
+-- @doc
+-- Returns aggregated total metrics for episodes combining data from Spotify, Apple Podcasts, and hosting providers over the specified date range.
+-- Fields: Episode identifiers, Total Streams, Plays, Listeners, Downloads, Time Listened across all platforms
+
 SELECT 
     -- Episode identifiers from mapping view
     em.account_id,

diff --git a/db_schema/queries/v1/ping.sql b/db_schema/queries/v1/ping.sql
@@ -1 +1,5 @@
+-- @doc
+-- Simple health check endpoint that echoes back the provided date parameters.
+-- Fields: Start Date, End Date, Result Status
+
 SELECT @start as start, @end as end, "pong" as result
diff --git a/db_schema/queries/v1/podcastAge.sql b/db_schema/queries/v1/podcastAge.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Spotify podcast listener demographics by age group with listener counts and percentages of total audience.
+-- Fields: Date, Age Group, Listeners Count, Percentage of Total
+
 WITH data as
 (
   SELECT

diff --git a/db_schema/queries/v1/podcastFollowers.sql b/db_schema/queries/v1/podcastFollowers.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns podcast follower metrics across platforms showing daily follower counts and growth trends.
+-- Fields: Date, Platform, Followers Count, Growth metrics
+
 SELECT * FROM podcastFollowers 
 WHERE
   account_id = @podcast_id

diff --git a/db_schema/queries/v1/podcastGender.sql b/db_schema/queries/v1/podcastGender.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Spotify podcast listener demographics broken down by gender and age group.
+-- Fields: Date, Gender, Listeners Count, Age Group
+
 WITH data as (
   SELECT *
   FROM spotifyPodcastAggregate

diff --git a/db_schema/queries/v1/podcastMetadata.sql b/db_schema/queries/v1/podcastMetadata.sql
@@ -1,5 +1,6 @@
--- Combined podcast metadata from Apple and Spotify platforms
--- Returns the latest metadata information for the podcast
+-- @doc
+-- Returns comprehensive podcast metadata including basic information, Spotify statistics, and Apple follower data.
+-- Fields: Account ID, Podcast Name, Artwork URL, Release Date, Publisher, Latest Platform Statistics
 
 SELECT 
     pm.account_id,

diff --git a/db_schema/queries/v1/spotifyCountries.sql b/db_schema/queries/v1/spotifyCountries.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns Spotify podcast listener geographic distribution by country with listener counts and percentages.
+-- Fields: Country Short Code, Listeners Count, Percentage of Total
+
 WITH
 data as (
 SELECT 

diff --git a/db_schema/queries/v1/spotifyImpressions.sql b/db_schema/queries/v1/spotifyImpressions.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns daily Spotify impression metrics showing how many times the podcast appeared in user interfaces.
+-- Fields: Account ID, Date, Impressions Count
+
 SELECT
 	account_id,
 	date,

diff --git a/db_schema/queries/v1/spotifyImpressionsFunnel.sql b/db_schema/queries/v1/spotifyImpressionsFunnel.sql
@@ -1,5 +1,6 @@
--- Gets the latest 30-day funnel data (impressions -> considerations -> streams)
--- Returns data for the most recent day within the requested date range
+-- @doc
+-- Returns Spotify conversion funnel data showing the progression from impressions to considerations to streams with conversion rates.
+-- Fields: Account ID, Date, Step ID, Step Count, Conversion Percentage
 
 SELECT DISTINCT 
 	account_id,

diff --git a/db_schema/queries/v1/spotifyImpressionsSources.sql b/db_schema/queries/v1/spotifyImpressionsSources.sql
@@ -1,4 +1,6 @@
--- Gets impressions breakdown by source (HOME, SEARCH, LIBRARY, OTHER)
+-- @doc
+-- Returns Spotify impressions broken down by source location (HOME, SEARCH, LIBRARY, OTHER) showing where users discover the podcast.
+-- Fields: Account ID, Date Start, Date End, Source ID, Impression Count
 
 SELECT DISTINCT
     account_id,

diff --git a/db_schema/queries/v1/spotifyPlaysSum.sql b/db_schema/queries/v1/spotifyPlaysSum.sql
@@ -1,3 +1,7 @@
+-- @doc
+-- Returns aggregated Spotify podcast metrics totals including episodes, starts, streams, listeners, and followers over the date range.
+-- Fields: Podcast ID, Total Episodes, Starts, Streams, Listeners, Followers
+
 SELECT
   account_id as podcast_id,
   SUM(spm_total_episodes) as spotify_total_episodes,