VotingAPI: Data storage overview

This information is intended for developers creating modules that use VotingAPI.

VotingAPI acts as a traffic cop for a large pool of voting data: modules throw votes at it and ask for results back. It assumes nothing about the kinds of content being voted on. Instead, it lets modules mark each vote with a 'content type' and 'content id', so that the same APIs can be used to rate nodes, comments, users, aggregator items, or even other votes (in a Slashdot-esque meta-moderation system).

Two kinds of records are stored: individual votes by each user on each piece of content, and cached 'result' records that aggregate calculated values like the average vote for a piece of content, how many people voted on it, etc. Each time a user votes, the cached result records are automatically recalculated. This means that no 'on-the-fly' calculations have to be done when displaying content ratings.

Each individual vote has the following properties:

content_type

This usually corresponds to a type of Drupal content, like 'node' or 'comment' or 'user'.

content_id

The key ID of the content being rated.

value

This is the actual value of the vote that was cast by the user.

value_type

This determines how vote results are totaled. VotingAPI supports three value types by default: 'percent' votes are averaged, 'points' votes are summed up, and 'option' votes get a count of votes cast for each specific option. Modules can use other value_types, but must implement their own calculation functions to generate vote results -- more on that later.

tag

Modules can use different tags to store votes on specific aspects of a piece of content, like 'accuracy' and 'timeliness' of a news story. If you don't need to vote on multiple criteria, you should use the default value of 'vote'. If you use multiple tags, it is STRONGLY recommended that you provide an average or 'overall' value filed under the default 'vote' tag. This gives other modules that display voting data a single value to key on for sorting, etc.

uid

The user ID of the person who voted.

timestamp

The time the vote was cast.

hostname

The IP address of the host the vote was cast from.

Each cached result record has the following properties:

content_type

The same meaning as an individual vote object.

content_id

The same meaning as an individual vote object.

value_type

The same meaning as an individual vote object.

tag

The same meaning as an individual vote object.

function

The aggregate function that's been calculated -- for example, 'average', 'sum', and so on.

value

The value of the aggregate function.

timestamp

The time the results were calculated.