Clarification on Target documents in CouchDB

Technical Support
,
1

Looking at the documentation for Target documents in CouchDB, I have some questions.

Q1. Which database are these stored in once they are synced to the server?

I assume in the medic DB, but just want to confirm.

Q2. The documentation says that there is “one [Targets document] per analytics reporting period”. Given the scenario below, can you confirm my understanding is correct?

Scenario: If you had 2x “All time” targets, 5x “monthly” targets, and 1x “quarterly” target (that uses a function to evaluate quarters), my understanding is that…

  • The 2x “All time” targets would both be represented in 1 persistent Target document that has 2 array elements in the “targets” key. This document would just keep getting updated for perpetuity, there would only ever be one Target document that represents these 2 Targets .
  • The 5x “monthly” targets would have one Target document per month that has 5x array elements in the “targets” key. One new Target document would be created every month for these 5x Targets.
  • The 1x “quarterly” target would have one Target document per quarter that has this one Target in it. One new Target document would be created every quarter for this Target.

Q3. The documentation says that Target documents are “updated a maximum of once per day”. Is that a typo?

It seems weird that if you had a Target that counts pregnancy registrations in a given month, and you registered one in the morning and one in the afternoon, the one in the afternoon wouldn’t be counted until the next day.

Q4. From the Target document, can you please clarify how to know the “analytics reporting period”?

The _id of the Target document has the format:

"_id": "target~2000-01~user-contact-guid~org.couchdb.user:agatha",

I assume the data between the first two ~ represents the reporting period, and in this example, I assume this means January of the year 2000. What will it be for “all time” Targets or Targets whose date property is based on a function?

Q5. For Targets with a type = percent, what information will be available in the Targets document?

Will the numerator and denominator be available? Will the percentage be represented as a decimal?

1 Like
2

Hey @michael! These are all great questions - some of them pointing to weaknesses in our documentation and others perhaps raising questions about our implementation.

Q1. Which database are these stored in once they are synced to the server?

Yes, these documents are stored into the medic database once the user syncs. The documents will be duplicated to Postgres via the couch2pg.

Q2. The documentation says that there is “one [Targets document] per analytics reporting period”. Given the scenario below, can you confirm my understanding is correct?

I think this should simply indicate that there is “one target document per user per month.” Each target document contains data for every target on the user’s device (any target where context evaluates as true). So targets with date: 'reported' and date: 'now' will both have their latest viewed score in the target document.

Q3. The documentation says that Target documents are “updated a maximum of once per day”. Is that a typo?

Not a typo, but perhaps a bit weird… This behavior was chosen because recalculating the target document and diffing it vs what exists was deemed to be an unnecessary performance burden (both time to compute and data required for syncing the updated document). But that may not be the correct strategy. In the original spec for the feature, the target document was only written once per month! If you file a bug, we can re-evaluate this.

Maybe this is too much information… but as it stands, target documents were designed to report an accurate month-end value. If you’re using them for real-time data before the month is over, the odd thing about target documents (and tasks) is that they are an insight into the user’s experience (they report what the user saw); they are not an insight into the user’s document state (what the user would see if they viewed targets tab). In that way they are quite different from postgres/impact queries. If we take the example you gave of two pregnancy registrations in a day, if the user creates these pregnancy registrations and doesn’t view the tasks tab or targets tab on the day: then the target document will not update at all. This existing “loose” behavior of the target docs is part of why a “once-per-day” update isn’t so crazy. There is already a disconnect that can cause data in target documents to lag reality.

Q4. From the Target document, can you please clarify how to know the “analytics reporting period”?

Hopefully this is clarified by the answer in Q2. There is one target document per user per month, so for the example here, you’re looking at the target document for user agath for Jan 2000.

Q5. For Targets with a type = percent , what information will be available in the Targets document?

I’ll update the document. The schema includes percent which is a rounded integer along-side the numerator (pass) and denominator (total).

targets: [{
  "id": "2-home-visits-per-fam",
  "value": {
    "pass": 5,
    "total": 8,
    "percent": 63
  }
}]
1 Like