Edit

Schedule an indexer in Azure AI Search

Note

Azure AI Search is available through the Azure portal, REST APIs, and Azure SDKs. It also underpins Foundry IQ, the managed knowledge layer that transforms enterprise content into reusable, permission-aware knowledge bases for agents in the Microsoft Foundry portal.

Set the schedule property to configure indexers to run on a schedule. Indexer scheduling is useful in situations such as:

  • Source data changes over time, and you want the indexer to automatically process the difference.
  • Source data is very large, and you need a recurring schedule to index all of the content.
  • An index is populated from multiple sources using multiple indexers, and you want to stagger the jobs to reduce conflicts.

When indexing can't complete within the typical 2-hour processing window, schedule the indexer to run on a 2-hour cadence to work through a large volume of data. As long as your data source supports change detection logic, indexers can automatically pick up where they left off on each run.

Once you put an indexer on a schedule, it stays on the schedule until you clear the interval or start time, or set disabled to true. If a scheduled indexer stops triggering unexpectedly, see Scheduling behavior FAQ for recovery steps. Leaving the indexer on a schedule when there's nothing to process doesn't impact system performance. Checking for changed content is a relatively fast operation.

Prerequisites

  • A valid indexer configured with a data source and index.

  • Change detection in the data source. Azure Storage and SharePoint have built-in change detection. For other data sources, such as Azure SQL and Azure Cosmos DB, you must enable change detection manually.

Schedule definition

A schedule is part of the indexer definition. If you omit the schedule property, the indexer only runs on demand. The property has two parts.

Property Description
"interval" (required) The amount of time between the start of two consecutive indexer executions. The smallest interval allowed is 5 minutes, and the longest is 1,440 minutes (24 hours). Format it as an XSD "dayTimeDuration" value (a restricted subset of an ISO 8601 duration value).

The pattern for this value is: P(nD)(T(nH)(nM)).

Examples: PT15M for every 15 minutes, PT2H for every two hours.
"startTime" (optional) Specify the start time in coordinated universal time (UTC). If you omit this value, the current time is used. This time can be in the past, in which case the first execution is scheduled as if the indexer has been running continuously since the original start time.

The following example is a schedule that starts on January 1 at midnight and runs every two hours.

{
    "dataSourceName" : "hotels-ds",
    "targetIndexName" : "hotels-idx",
    "schedule" : { "interval" : "PT2H", "startTime" : "2024-01-01T00:00:00Z" }
}

Configure a schedule

Specify schedules in an indexer definition. To set up a schedule, use the Azure portal, REST APIs, or an Azure SDK.

  1. Go to your search service in the Azure portal.
  2. On the left pane, select Indexers.
  3. Open an indexer.
  4. Select Settings.
  5. Scroll down to Schedule, and then choose Hourly, Daily, or Custom to set a specific date, time, or custom interval.

Switch to the Indexer Definition (JSON) tab at the top of the index to view the schedule definition in XSD format.

Scheduling behavior FAQ

Can I run multiple indexer jobs in parallel?

You can run multiple indexers simultaneously, but each indexer is a single instance. You can't run two copies of the same indexer concurrently.

For text-based indexing, the scheduler can start as many indexer jobs as the search service supports, which the number of search units determines. For example, if the service has three replicas and four partitions, you can have 12 indexer jobs in active execution, whether initiated on demand or on a schedule.

For skills-based indexing, indexers run in a specific execution environment. For this reason, the number of service units doesn't affect the number of skills-based indexer jobs you can run. Multiple skills-based indexers can run in parallel, but doing so depends on content processor availability within the execution environment.

Do scheduled jobs always start at the designated time?

Indexer processes can queue up and might not start exactly at the time posted, depending on the processing workload and other factors. For example, if an indexer happens to still be running when its next scheduled execution is set to start, the pending execution is postponed until the next scheduled occurrence, which allows the current job to finish.

To make this behavior more concrete, consider the following example. Suppose you configure an indexer schedule with an interval of hourly and a start time of January 1, 2024 at 8:00:00 AM UTC. Here's what could happen when an indexer run takes longer than an hour:

  1. The first indexer execution starts at or around January 1, 2024 at 8:00 AM UTC. Assume this execution takes 20 minutes (or any amount of time that's less than 1 hour).

  2. The second execution starts at or around January 1, 2024 9:00 AM UTC. Suppose that this execution takes 70 minutes - more than an hour – and it doesn't complete until 10:10 AM UTC.

  3. The third execution is scheduled to start at 10:00 AM UTC, but at that time the previous execution is still running. This scheduled execution is then skipped. The next execution of the indexer doesn't start until 11:00 AM UTC.

In rare cases, such as during maintenance or when recovering from transient conditions, the system queues up multiple indexer runs. When this condition occurs, the indexer executes pending workloads sequentially within the scheduled window. For example, if an indexer is scheduled to run hourly and several runs were delayed or triggered on-demand, those queued up jobs execute back-to-back until the queue is drained. These runs aren't extra runs, but represent previously scheduled or requested executions. While this behavior is uncommon in most scenarios, the indexer is designed to eventually process all queued tasks to maintain consistency and data freshness.

Note

If you have strict indexer execution requirements that are time-sensitive, consider using the push API model so you can control the indexing pipeline directly.

What happens if indexing fails repeatedly on the same document?

If you set an indexer to a certain schedule but it repeatedly fails on the same document each time, the indexer begins running on a less frequent interval (up to the maximum interval of at least once every 2 hours or 24 hours, depending on different implementation factors) until it successfully makes progress again. If you believe you fixed the underlying issue, run the indexer manually. If indexing succeeds, the indexer returns to its regular schedule. If the indexer doesn't return to its regular schedule after a successful manual run, see the next question.

A scheduled indexer stopped triggering. How do I reset its schedule?

If a scheduled indexer stops running, disable and then re-enable it to reset the schedule. A sign that this recovery is needed: no new runs appear in execution history even though the schedule is configured and the data source changed.

Setting disabled to true suspends the schedule. Setting it back to false (or omitting the property) resumes scheduling, using the current time as the new baseline for the configured interval.

  1. Go to your search service in the Azure portal.
  2. Select Indexers.
  3. Select the indexer to open it.
  4. Select Settings.
  5. Set the indexer to Disabled.
  6. Select Save.
  7. Set the indexer back to Enabled.
  8. Select Save.
  9. Select the Execution history tab and verify that a new run appears within the next scheduled interval.

Note

Re-enabling the indexer resets the schedule relative to the current time, not the original startTime. For example, if the interval is two hours and you re-enable at 3:15 PM, the next scheduled run is at approximately 5:15 PM.

Next steps

For indexers that run on a schedule, you can monitor operations by retrieving status from the search service, or get detailed information by enabling resource logging.

  • Last updated on