When is sqid not qid?

sqid != qid when you have a queue with multiple subqueues, for example when you use the smartqueue taxonomy submodule.

The same is true when you use User smartqueues, which uses the uid of the user to identify the subqueue. I started a patch (see #675484: Allow multiple subuqueues in standard nodequeues) that never got completed for lack of demand, to allow multiple subqueues per nodequeue, and that was one of the sticking points; if you don't have a specific identifier to use (such as tid or uid), how do you determine the sqids for the subqueues so they don't clash?

The thing that you have to get your head around is that a nodequeue isn't an item itself - it's just a wrapper for a subqueue, or group of subqueues as is the case with the taxonomy and user smartqueues. Once you grasp that, it makes it much easier to understand what's going on.

I've been working on another nodequeue issue, and in looking at this I realized that what I said above about the sqid was wrong. The reason I say this is that the sqid is generated in the db when it is created in nodequeue_add_subqueue(). sqid is an auto_increment column in the nodequeue_subqueue table, and only the qid, reference, and title are inserted, so the sqid value is incremented from the previous one, regardless of which qid it goes with.

function nodequeue_add_subqueue(&$queue, $title, $reference = NULL) {
  if (empty($reference)) {
    $insert_reference = "";
  }
  else {
    $insert_reference = $reference;
  }

  $subqueue = new stdClass();;
  $subqueue->reference = $reference;
  $subqueue->qid = $queue->qid;
  $subqueue->title = $title;

  db_query("INSERT INTO {nodequeue_subqueue} (qid, reference, title) VALUES (%d, '%s', '%s')", $queue->qid, $insert_reference, $title);

  $subqueue->sqid = db_last_insert_id('nodequeue_subqueue', 'sqid');

  // If somehow the $reference is null, here we set it to the sqid.
  // We have to do it here, because before the insert we don't know what the sqid will be.
  if (empty($reference)) {
    db_query("UPDATE {nodequeue_subqueue} SET reference = '%s' WHERE sqid = %d", $subqueue->sqid, $subqueue->sqid);
  }

  return $subqueue;
}

In a normal nodequeue, there is only one subqueue, so if you are only adding normal nodequeues, the sqid will be the same as the qid (which is my guess as to what was happening with your case). If, however, you add a couple nodequeues, and then a smartqueue with some subqueues, and then another regular nodequeue, the sqid won't match the qid any more.

The reference value, however, is different (and was what I meant to say instead of sqid in my comment above). With a regular nodequeue, there is no need for a unique reference value, and, as you can see from the code above, the reference value is just set to the qid if none is passed to the function. However, for smartqueues, reference needs to be a unique value since there are multiple subqueues. As mentioned above, for taxonomy smartqueues this is the tid and for user queues it's the uid (and is passed in via the smartqueue API). If you were to try to create another type of smartqueue, you would need to provide some sort of unique reference value that would tie that subqueue to whatever entity is using the subqueues.

Hopefully that helps some more.