Priority

Priority allows you to dynamically execute some runs ahead or behind others based on any data. This allows you to prioritize some jobs ahead of others without the need for a separate queue. Some use cases for priority include:

Giving higher priority based on a user's subscription level, for example, free vs. paid users.
Ensuring that critical work is executed before other work in the queue.
Prioritizing certain jobs during onboarding to give the user a better first-run experience.

How to configure priority

export default inngest.createFunction(
  {
    id: "ai-generate-summary",
    priority: {
      // For enterprise accounts, a given function run will be prioritized
      // ahead of functions that were enqueued up to 120 seconds ago.
      // For all other accounts, the function will run with no priority.
      run: "event.data.account_type == 'enterprise' ? 120 : 0",
    },
  },
  { event: "ai/summary.requested" },
  async ({ event, step }) => {
    // This function will be prioritized based on the account type
  }
);

Configuration reference

run - A dynamic factor expression, that evaluates to seconds, to prioritize the function by. Returning a positive number will increase that priority ahead of other jobs already in the queue. Returning a negative number will delay the function run's jobs by the given value in seconds.

How priority works

Functions are scheduled in a priority queue based on the time they should run. By default, all functions are enqueued at the current time (a factor of 0). If a function has priority configured, Inngest evaluates the run expression for each new function run based on the input event's data. The run expression should return a factor, in seconds, (positive or negative) to adjust the priority of the function run.

Expressions that return a positive number will increase the priority of the function run ahead of other jobs already in the queue by the given value in seconds. The function will be run ahead of other jobs that were enqueued up to that many seconds ago. For example, if a function run is scheduled with a factor of 120, it will run ahead of any jobs enqueued in the last 120 seconds, given that they are still in the queue and have not completed.

Expressions that return a negative number will delay the function run by the given value in seconds.

Practical example

Given we have three jobs in the queue, each which was enqueued at the following times:

Jobs:          [A,        B,        C       ]
Priority/Time: [12:00:10, 12:00:40, 12:02:10]

If the current time is 12:02:30, and two new jobs are enqueued with the following run factors:

- Job X: factor 0
- Job Y: factor 120

Then Job Y will run ahead of Job X. Job Y will also run before any jobs scheduled 120 seconds beforehand. The queue will look like this:

Jobs:          [A,        Y,        B,        C,        X     ]
Priority/Time: [12:00:10, 12:00:30, 12:00:40, 12:02:10, 12:02:30]
                          │                             │
                          └ 12:02:30 - 120s = 12:00:30  └ 12:02:30 - 0s = 12:02:30

Job Y was successfully prioritized by a factor of 120 seconds ahead of other jobs in the queue.

Combining with concurrency

Prioritization is most useful when combined with a flow control option that limits throughput, such as concurrency. Jobs often wait in the queue when limiting throughput, so prioritization allows you to control the order in which jobs are executed in that backlog.

Limitations

The highest priority is 600 (seconds).
The lowest priority is -600 (seconds).

Platform