doc/couch/documents.txt

   1
   2
   3                        Document Overview
   4                        ~~~~~~~~~~~~~~~~~
   5
   6
   7 This file describes the documents that will be used in the CouchDB based
   8 backend of the gpodder.net webservice.
   9
  10 For each document type the models (used in the current relational backend)
  11 which will be replaced by it are listed.
  12
  13
  14
  15   User
  16 ========
  17
  18 A registered (but probably not yet activated) user and all his devices.
  19
  20 Replaces Models
  21  * User (from django)
  22  * UserProfile
  23  * RegistrationProfile (from django-registration)
  24  * Device
  25  * SyncGroup
  26
  27 Example Document
  28 {
  29     username:         "stefan",
  30     email:            "stefan@gpodder.net",,
  31     password:         "asdf$asdfasdf$asdfsdfa",
  32     is_active:        False,
  33     registration_key: "ad18719239817389ad",
  34
  35     devices: [
  36         {
  37             "_id":   "872348923987492834",
  38             "user":  "stefan",
  39             "id":    "n900",
  40             "type":  "mobile",
  41             "label": "N900"
  42         },
  43         { ... }
  44     ],
  45
  46     synchronized: [
  47         ["872348923987492834", "3498503485093495"],
  48         ["9384053405", "90548903458"]
  49     ]
  50 }
  51
  52
  53   Podcast
  54 ===========
  55
  56 If a Podcast does not belong to a group, it is a document on its own.  The
  57 "subscriber" field contains historical subscriber counts. The "tags" field
  58 contains all tags that are fetched in some automated way (ie not entered by a
  59 user).
  60
  61 A Podcast contains recent subscriber data in the "subscribers" property. To
  62 keep the Podcast objects small, subscriber data is periodically moved to the
  63 podcast's PodcastSubscriberData object.
  64
  65
  66 Replaces Models
  67  * Podcast
  68  * HistoricPodcastData
  69  * RelatedPodcast
  70  * DirectoryEntry
  71  * PodcastPublisher
  72  * SearchEntry
  73  * ToplistEntry
  74
  75 Example Document
  76 {
  77     _id: "118913287192379173298"
  78     name: "Cool Podcast",
  79     feed_url: "http://podcast.com/mp3.xml",
  80     description: "..."
  81     subscribers: [{timestamp: "2010-09-01", subscriber_count: 120}, ... },
  82     related_podcasts: ["34059384598304850", "23480128409230482"],
  83     tags: {
  84         feed: [["technology", 50], ["news", 20]],
  85         delicious: [["technews", 10]]
  86     },
  87     publishers: ["stefan"],
  88     merged_ids: [ ...],
  89     language: "en",
  90     episodes: {
  91         19384038450938450983: { Episode },
  92         20928340283040234820. { Episode },
  93     },
  94     content_types: ["image", "audio"]
  95 }
  96
  97
  98   PodcastGroup
  99 ================
 100
 101 Represents a group of podcast and contains all podcasts assigned to it.
 102 Once a Podcast is assigned to a group, its Podcast document in deleted
 103 and moved into the PodcastGroup.
 104
 105 Replaces Models:
 106  * Podcast
 107  * PodcastGroup
 108
 109 Example Document
 110 {
 111     _id: "9238409283402830480",
 112     oldid: 10,
 113     name: "Cool Podcast",
 114     podcasts: [
 115         {
 116             id: "118913287192379173298",
 117             name: "Cool Podcast",
 118             group: "9238409283402830480",  # the _id of the group for
 119                                            # referring to it when the the
 120                                            # podcast is referred to separately
 121             group_member_name: "MP3",             # required if Podcast is member of a group
 122             feed_url: "http://podcast.com/mp3.xml",
 123             description: "..."
 124             subscribers: [[2010-09-01, 120], [2010-09-01, 130]],
 125             related_podcasts: ["34059384598304850", "23480128409230482"],
 126             tags: ["technology", "news"],
 127             publishers: ["stefan"],
 128             episodes: Episode-Dict
 129         },
 130         { ... }
 131     ],
 132 }
 133
 134
 135   PodcastSubscriberData
 136 =========================
 137
 138 Contains the older subscriber data for a Podcast. This can be used to retrieve changes in the number of subscribers of a podcast.
 139
 140 Replaces Models:
 141  * HistoricPodcastData
 142
 143 Example Document
 144 {
 145     podcast: "118913287192379173298",
 146     subscribers: [
 147         {timestamp: "2010-09-01", subscriber_count: 120},
 148         {timestamp: "2010-10-01", subscriber_count: 125},
 149         {timestamp: "2010-11-01", subscriber_count: 210},
 150     ],
 151 }
 152
 153
 154   Episode
 155 ===========
 156
 157 An episode, in concept, belongs to a Podcast (not a PodcastGroup) but is a
 158 standalone document. It has optional support for multiple media files (eg Audio
 159 and PDF Show Notes). The fields listeners and recent_listeners are
 160 regularly updated with aggregated data to substitute queries based on time.
 161
 162 Replaces Models:
 163  * Episode
 164  * SearchEntry
 165  * ToplistEntry
 166
 167 Example Document
 168 {
 169     _id:    "19384038450938450983",
 170     title: "Cool Episode of Cool Podcast",
 171     podcast: "118913287192379173298",
 172     media_urls: ["http://podcast.com/episode1.mp3", "http://podcast.com/episode1.pdf"],
 173     released: "2010-09-20 12:00",
 174     tags: ["opensource", "technology"],
 175     merged_ids: ["908345083045", "29380423849"],
 176     media_types: ["audio"],
 177     listeners: [["2010-09-20", 20], ["2010-09-21", 15]],
 178     recent_listeners:  75,
 179     language: "en"
 180 }
 181
 182
 183   PodcastUserState
 184 ====================
 185
 186 Contains everything that a User has done with a Podcast. The podcast is
 187 referenced by the "ref_url" which is the URL that was received via the API. It
 188 can be used in API responses so that the user receives exactly the same URL he
 189 has sent (the Podcast document could contain several URLs).
 190
 191 Replaces Models:
 192  * SubscriptionAction
 193  * PodcastTag
 194  * SubscriptionMeta
 195  * obsolete: Subscription, BackensSubscription
 196
 197 Example Document
 198 {
 199     _id: "3893745983453948589345",
 200     user: "345983045035480345809",
 201     user_oldid: 4253,
 202     podcast: "118913287192379173298",
 203     ref_url: "http://example.com/podcast.xml",
 204     actions:
 205         [
 206             {
 207              action:    "subscribed",
 208              timestamp: "2010-09-10",
 209              device:    "872348923987492834"
 210             },
 211             {
 212              action:    "unsubscribed",
 213              timestamp: "2010-09-15",
 214              device:    "872348923987492834"
 215             }
 216         ],
 217     tags: ["technews"]
 218     settings: { ... }
 219 }
 220
 221
 222   Suggestions
 223 ===================
 224
 225 Contains the Podcast Suggestions and related meta-data (blacklist,
 226 suggestion-ratings) of a User. This is not places into PodcastUserState because
 227 the user did not yet interact with the Podcast directly.
 228
 229 Replaces Models:
 230  * SuggestionEntry
 231  * SuggestionBlacklist
 232  * Rating
 233
 234 Example Document
 235 {
 236     user: "stefan",
 237     podcasts: [
 238         "119018023981293801823",
 239         "192840890284092834093"
 240     ],
 241     blacklist: [
 242         "456045698409586045860",
 243         "935937498573549739485"
 244     ],
 245     ratings: [
 246         { timestamp: "2010-09-13", rating: -1},
 247         { timestamp: "2010-09-15", rating:  1}
 248     ],
 249 }
 250
 251
 252   EpisodeUserState
 253 ====================
 254
 255 A EpisodeUserState contains everything that a User has done with an Episode.
 256 The episode is referenced by the "ref_url" and "podcast_ref_url" which contain
 257 the URLs for the episode and the podcast, exactly as they have been received
 258 via the API. These values can also be used in API responses to refer to exactly
 259 the same URL as in the request (both Episode and Podcast documents can contain
 260 several URLs).
 261
 262 Replaces Models
 263  * EpisodeAction
 264  * EpisodeFavorite
 265  * Chapter
 266  * EpisodeSettings
 267  * obsolete: Listener
 268
 269 Example Document
 270 {
 271     episode: "3893745983453948589345",
 272     podcast: "118913287192379173298",
 273     ref_url: "http://podcast.com/episode-1.mp3",
 274     podcast_ref_url: "http://podcast.com/mp3.xml",
 275     actions:
 276         [
 277             {
 278              action:    "download",
 279              file:      "http://podcast.com/episode-1.mp3",
 280              timestamp: "2010-09-10",
 281              device:    "872348923987492834"
 282             },
 283             {
 284              action:    "play",
 285              file:      "http://podcast.com/episode-1.mp3",
 286              timestamp: "2010-09-15",
 287              device:    "872348923987492834"
 288             }
 289         ],
 290     chapters: [
 291         {
 292             from:          "02:10",
 293             to:            "04:20",
 294             advertisement: false,
 295             label:         "interview",
 296         }
 297     ],
 298     settings: { ... }
 299 }
 300
 301
 302   Advertisement
 303 =================
 304
 305 Contains an advertisement for a Podcast
 306
 307 Replaces Models:
 308  * Advertisement
 309
 310 Example Document
 311 {
 312     user:    "stefan",
 313     podcast: "118913287192379173298",
 314     start:   "2010-09-01",
 315     end:     "2010-09-15"
 316 }
 317
 318
 319   SanitizingRule
 320 =====================
 321
 322 Contains a URL Sanitizing Rule.
 323
 324 Replaces Models:
 325  * URLSanitizingRule
 326
 327 Example Document
 328 {
 329     slug:         "feedburner-feeds2",
 330     applies_to:   ["podcast", "episode"],
 331     search:       "http://feeds2\.feedburner\.com",
 332     replace_by:   "http://feeds.feedburner.com",
 333     descriptions: "Replace {feeds2 => feeds}.feedburner.com",
 334     priority:     100,
 335 }
 336
 337
 338   Category
 339 ============
 340
 341 Represents a category within the Podcast Directory.
 342
 343 Replaces Models
 344  * PodcastTag
 345
 346 Example Document
 347 {
 348     label:     "Technology",
 349     spellings: ["technology", "tech"],
 350     weight:    1200,
 351     updated:   "2010-09-28T08:38:03Z",
 352 }
 353
 354
 355   Other Models
 356 ================
 357
 358 * SecurityToken: has been moved to various documents, depending on previous
 359                  usage
 360