Prioritized Jobs

Control job processing order with priority values

Overview

Jobs can include a priority option to affect processing order. Using priorities, job processing order is determined by the specified priority value instead of following FIFO or LIFO patterns.

Adding prioritized jobs is slower than regular jobs, with O(log(n)) complexity relative to the number of jobs in the prioritized set.

Priority Values

From src/classes/job.ts:47:

export const PRIORITY_LIMIT = 2 ** 21;

export class Job {
  /**
   * Ranges from 0 (highest priority) to 2 097 152 (lowest priority). Note that
   * using priorities has a slight impact on performance,
   * so do not use it if not required.
   * @defaultValue 0
   */
  priority = 0;
}

Priorities range from 1 to 2,097,152, where lower numbers have higher priority.

Jobs without a priority assigned get the highest priority (priority 0) and are processed before jobs with explicit priorities.

Basic Usage

import { Queue } from 'bullmq';

const myQueue = new Queue('Paint');

await myQueue.add('wall', { color: 'pink' }, { priority: 10 });
await myQueue.add('wall', { color: 'brown' }, { priority: 5 });
await myQueue.add('wall', { color: 'blue' }, { priority: 7 });

// The wall will be painted first brown (5), then blue (7), and finally pink (10)

If multiple jobs have the same priority value, they are processed in FIFO (First-In, First-Out) order.

Change Priority

You can change a job’s priority after insertion using the changePriority method:

import { Job, Queue } from 'bullmq';

const queue = new Queue('Paint');
const job = await Job.create(queue, 'test2', { foo: 'bar' }, { priority: 16 });

await job.changePriority({
  priority: 1,
});

From src/classes/job.ts:1059:

/**
 * Change job priority.
 *
 * @param opts - options containing priority and lifo values.
 * @returns void
 */
async changePriority(opts: {
  priority?: number;
  lifo?: boolean;
}): Promise<void> {
  await this.scripts.changePriority(this.id, opts.priority, opts.lifo);
  this.priority = opts.priority || 0;
}

Change Priority with LIFO

You can also combine priority changes with LIFO ordering:

const job = await Job.create(queue, 'test2', { foo: 'bar' }, { priority: 16 });

await job.changePriority({
  lifo: true,
});

Get Prioritized Jobs

Prioritized is a separate state. Use getJobs or getPrioritized to retrieve them:

// Method 1: Using getJobs
const jobs = await queue.getJobs(['prioritized']);

// Method 2: Using getPrioritized
const jobs2 = await queue.getPrioritized();

Get Counts per Priority

Retrieve the count of jobs for specific priority values:

const counts = await queue.getCountsPerPriority([1, 0]);
/*
{
  '1': 11,
  '0': 10
}
*/

This method returns:

• Jobs in prioritized status (priorities > 0)
• Jobs in waiting status (priority 0)

Job Options Interface

From src/interfaces/base-job-options.ts:13:

interface DefaultJobOptions {
  /**
   * Ranges from 0 (highest priority) to 2 097 152 (lowest priority). Note that
   * using priorities has a slight impact on performance,
   * so do not use it if not required.
   * @defaultValue 0
   */
  priority?: number;
}

Priority Validation

From src/classes/job.ts:1597:

if (this.opts.priority) {
  if (Math.trunc(this.opts.priority) !== this.opts.priority) {
    throw new Error(`Priority should not be float`);
  }

  if (this.opts.priority > PRIORITY_LIMIT) {
    throw new Error(`Priority should be between 0 and ${PRIORITY_LIMIT}`);
  }
}

Priority values must be:

• Integers (no decimals)
• Between 0 and 2,097,152

Use Cases

VIP Customer Processing

Process VIP customer orders before regular customers:

const orderQueue = new Queue('orders');

// VIP customer order (high priority)
await orderQueue.add(
  'processOrder',
  { orderId: '123', customerId: 'vip-456' },
  { priority: 1 }
);

// Regular customer order (lower priority)
await orderQueue.add(
  'processOrder',
  { orderId: '124', customerId: 'reg-789' },
  { priority: 10 }
);

Severity-Based Alerts

Process critical alerts before warnings:

const alertQueue = new Queue('alerts');

await alertQueue.add(
  'sendAlert',
  { message: 'Server down!', level: 'critical' },
  { priority: 1 }
);

await alertQueue.add(
  'sendAlert',
  { message: 'High CPU usage', level: 'warning' },
  { priority: 5 }
);

Dynamic Priority

Adjust priority based on business logic:

const job = await queue.add('task', data, { priority: 10 });

// Later, if conditions change...
if (urgentCondition) {
  await job.changePriority({ priority: 1 });
}

Performance Considerations

Complexity

O(log(n)) for adding prioritized jobs vs O(1) for regular jobs

Use Sparingly

Only use priorities when necessary for your use case

Batch Operations

Consider batching jobs of the same priority to reduce overhead

Monitor Performance

Track metrics to ensure priorities don’t create bottlenecks

Read More

Faster Priority Jobs

Blog post about priority job performance improvements

Change Priority API

changePriority API Reference

Get Prioritized API

getPrioritized API Reference

Counts per Priority

getCountsPerPriority API Reference