The Migrate module uses classes derived from the abstract class MigrateSource to encapsulate source data to be imported. In a Migration class constructor, there must be a call like:
$this->source = new MigrateSourceSQL($query);
An instance of a MigrateSource class (with appropriate arguments to indicate where the data is coming from) must be created and assigned to $this->source.
In this section, we examine the source classes that are bundled with Migrate, and explain how to create your own source class.
All sources accept an array of options for modifying their default behavior. The following options are implemented in MigrateSource itself (i.e., they are available to all source classes.
If you set this option to TRUE:
$this->source = new MigrateSourceSQL($query, array(), NULL, array('cache_counts' => TRUE));
then the count of total records available from the source will be cached. That is, it will only be actually computed directly from the source if it has never been obtained before, if the general Drupal cache has been cleared, or you pass the --refresh option to the drush migrate-status command. This is quite useful in cases where obtaining the count is slow (such as from a large XML feed).
The skip_count option allows you to disable source record counting entirely, when for example the cost of counting is so high you don't want to do it even once.
The cache_key option specifies the name of the cache key for the count - the default value is an MD5 of the concrete source class string value (__toString), which might in some cases be duplicated for multiple source classes derived from a common ancestor.
Setting the track_changes option to TRUE will cause each incoming source row to be hashed (after prepareRow) and, if previously imported, compared to the previous value to determine whether the item should be re-imported. This is used to import changed as well as new records from the source, in cases where highwater marks aren't practical.