Skip to main content
Version: Next

externalRequestQueue

Represents a queue of URLs to crawl, which is used for deep crawling of websites where you start with several URLs and then recursively follow links to other pages. The data structure supports both breadth-first and depth-first crawling orders.

Each URL is represented using an instance of the Request class. The queue can only contain unique URLs. More precisely, it can only contain Request instances with distinct uniqueKey properties. By default, uniqueKey is generated from the URL, but it can also be overridden. To add a single URL multiple times to the queue, corresponding Request objects will need to have different uniqueKey properties.

Do not instantiate this class directly, use the RequestQueue.open function instead.

RequestQueue is used by BasicCrawler, CheerioCrawler, PuppeteerCrawler and PlaywrightCrawler as a source of URLs to crawl. Unlike RequestList, RequestQueue supports dynamic adding and removing of requests. On the other hand, the queue is not optimized for operations that add or remove a large number of URLs in a batch.

Example usage:

// Open the default request queue associated with the crawler run
const queue = await RequestQueue.open();

// Open a named request queue
const queueWithName = await RequestQueue.open('some-name');

// Enqueue few requests
await queue.addRequest({ url: 'http://example.com/aaa' });
await queue.addRequest({ url: 'http://example.com/bbb' });
await queue.addRequest({ url: 'http://example.com/foo/bar' }, { forefront: true });

Implements

  • IStorage
  • IRequestManager

Index

Properties

Accessors

Methods

Properties

externalreadonlybackend

backend: RequestQueueBackend

externalreadonlyid

id: string

externalreadonlylog

log: CrawleeLogger

externaloptionalreadonlyname

name?: string

Accessors

externalstats

  • get stats(): RequestQueueStats

  • Backend-independent usage counters tracked for this request queue (write operations and queue-head reads issued to the underlying storage backend). Counted per backend call.

    Returns RequestQueueStats

Methods

external[asyncIterator]

  • [asyncIterator](): AsyncGenerator<CrawleeRequest<Dictionary>, void, unknown>

  • Returns AsyncGenerator<CrawleeRequest<Dictionary>, void, unknown>

externaladdRequest

  • addRequest(requestLike, options): Promise<RequestQueueOperationInfo>

  • Adds a request to the queue.

    If a request with the same uniqueKey property is already present in the queue, it will not be updated. You can find out whether this happened from the resulting QueueOperationInfo object.

    To add multiple requests to the queue by extracting links from a webpage, see the enqueueLinks helper function.

    Parameters

    • externalrequestLike: Source

      Request object or vanilla object with request data. Note that the function sets the uniqueKey and id fields to the passed Request.

    • externaloptionaloptions: RequestQueueOperationOptions

      Request queue operation options.

    Returns Promise<RequestQueueOperationInfo>

externaladdRequests

  • addRequests(requestsLike, options): Promise<BatchAddRequestsResult>

  • Adds requests to the queue in batches of 25. This method will wait till all the requests are added to the queue before resolving. You should prefer using queue.addRequestsBatched() or crawler.addRequests() if you don't want to block the processing, as those methods will only wait for the initial 1000 requests, start processing right after that happens, and continue adding more in the background.

    If a request passed in is already present due to its uniqueKey property being the same, it will not be updated. You can find out whether this happened by finding the request in the resulting BatchAddRequestsResult object.

    Parameters

    • externalrequestsLike: RequestsLike

      Request objects or vanilla objects with request data. Note that the function sets the uniqueKey and id fields to the passed requests if missing.

    • externaloptionaloptions: RequestQueueOperationOptions

      Request queue operation options.

    Returns Promise<BatchAddRequestsResult>

externaladdRequestsBatched

  • addRequestsBatched(requests, options): Promise<AddRequestsBatchedResult>

  • Adds requests to the queue in batches. By default, it will resolve after the initial batch is added, and continue adding the rest in the background. You can configure the batch size via batchSize option and the sleep time in between the batches via waitBetweenBatchesMillis. If you want to wait for all batches to be added to the queue, you can use the waitForAllRequestsToBeAdded promise you get in the response object.

    Parameters

    • externalrequests: ReadonlyDeep<RequestsLike>

      The requests to add

    • externaloptionaloptions: AddRequestsBatchedOptions

      Options for the request queue

    Returns Promise<AddRequestsBatchedResult>

externalcheckReadiness

  • checkReadiness(): Promise<RequestLoaderStatus>

  • Reports whether the queue has a request to hand over, is waiting on one, or is done.

    waiting means requests are in progress (fetched but not yet handled or reclaimed, possibly by another client sharing the queue) or a background add is still landing; neither has a clock, so no readyAt.

    Due to the nature of distributed storage used by the queue, finished may occasionally arrive a probe or two late, but it is never reported early.

    Returns Promise<RequestLoaderStatus>

externaldrop

  • drop(): Promise<void>

  • Removes the queue either from the Apify Cloud storage or from the local database, depending on the mode of operation.

    Returns Promise<void>

externalextendRequestProcessingTimeSecs

  • extendRequestProcessingTimeSecs(request, secs): Promise<boolean>

  • Parameters

    • externalrequest: CrawleeRequest<Dictionary>
    • externalsecs: number

    Returns Promise<boolean>

    RequestQueue.setExpectedRequestProcessingTimeSecs, which sizes every future lock, this only touches the one request it is given.

externalfetchNextRequest

  • fetchNextRequest<T>(): Promise<null | CrawleeRequest<T>>

  • Returns a next request in the queue to be processed, or null if there are no more pending requests.

    Once you successfully finish processing of the request, you need to call RequestQueue.markRequestAsHandled to mark the request as handled in the queue. If there was some error in processing the request, call RequestQueue.reclaimRequest instead, so that the queue will give the request to some other consumer in another call to the fetchNextRequest function.

    Note that the null return value doesn't mean the queue processing finished, it means there are currently no pending requests. To check whether all requests in queue were finished, use RequestQueue.checkReadiness instead.

    Returns Promise<null | CrawleeRequest<T>>

    Returns the request object or null if there are no more pending requests.

externalgetHandledCount

  • getHandledCount(): Promise<number>

  • Returns the number of handled requests.

    This function is just a convenient shortcut for:

    const { handledRequestCount } = await queue.getInfo();

    Returns Promise<number>

externalgetInfo

  • getInfo(): Promise<RequestQueueInfo>

  • Returns an object containing general information about the request queue.

    Example:

    {
      id: "WkzbQMuFYuamGv3YF",
      name: "my-queue",
      createdAt: new Date("2015-12-12T07:34:14.202Z"),
      modifiedAt: new Date("2015-12-13T08:36:13.202Z"),
      accessedAt: new Date("2015-12-14T08:36:13.202Z"),
      totalRequestCount: 25,
      handledRequestCount: 5,
      pendingRequestCount: 20,
    }

    Returns Promise<RequestQueueInfo>

    Throws - If the underlying storage no longer exists (e.g. it was deleted externally).

externalgetPendingCount

  • getPendingCount(): Promise<number>

  • Returns the total number of pending requests in the queue.

    Survives restarts and Actor migrations.

    Returns Promise<number>

externalgetRequest

  • getRequest<T>(uniqueKey): Promise<null | CrawleeRequest<T>>

  • Gets the request from the queue specified by its uniqueKey.

    Parameters

    • externaluniqueKey: string

      Unique key of the request.

    Returns Promise<null | CrawleeRequest<T>>

    Returns the request object, or null if it was not found.

externalgetTotalCount

  • getTotalCount(): Promise<number>

  • Returns the total number of requests in the queue (i.e. pending + handled).

    Survives restarts and actor migrations.

    Returns Promise<number>

externalmarkRequestAsHandled

  • markRequestAsHandled(request): Promise<null | RequestQueueOperationInfo>

  • Marks a request that was previously returned by the RequestQueue.fetchNextRequest function as handled after successful processing. Handled requests will never again be returned by the fetchNextRequest function.

    Parameters

    • externalrequest: CrawleeRequest<Dictionary>

    Returns Promise<null | RequestQueueOperationInfo>

externalpurge

  • purge(): Promise<void>

  • Remove all requests from the queue but keep the queue itself, resetting it so it can be reused (e.g. across multiple crawler.run() calls).

    Returns Promise<void>

externalreclaimRequest

  • reclaimRequest(request, options): Promise<null | RequestQueueOperationInfo>

  • Reclaims a failed request back to the queue, so that it can be returned for processing later again by another call to RequestQueue.fetchNextRequest. The request record in the queue is updated using the provided request parameter. For example, this lets you store the number of retries or error messages for the request.

    Parameters

    Returns Promise<null | RequestQueueOperationInfo>

externalrecordPacingSignal

  • recordPacingSignal(_signal): boolean

  • A queue hands requests out as fast as they are asked for; pacing is a job for a manager wrapped around it, such as ThrottlingRequestManager.

    Parameters

    • external_signal: PacingSignal

    Returns boolean

externalsetExpectedRequestProcessingTimeSecs

  • setExpectedRequestProcessingTimeSecs(secs): Promise<void>

  • Tells the queue how long a consumer expects to hold a fetched request before marking it handled or reclaiming it (typically the request-handler timeout plus padding), so that a storage backend that reserves requests via locking does not hand the same request out again while it is still being processed.

    Several consumers may share one queue (and therefore one client) in a single process, so we only ever raise the reservation duration, never lower it — otherwise a short-lived consumer could cut short the reservation of a long-lived one and have its in-flight request stolen.

    Parameters

    • externalsecs: number

    Returns Promise<void>

staticexternalopen

  • Opens a request queue and returns a promise resolving to an instance of the RequestQueue class.

    RequestQueue represents a queue of URLs to crawl, which is stored either on local filesystem or in the cloud. The queue is used for deep crawling of websites, where you start with several URLs and then recursively follow links to other pages. The data structure supports both breadth-first and depth-first crawling orders.

    For more details and code examples, see the RequestQueue class.

    Parameters

    • externaloptionalidentifier: null | string | StorageIdentifier

      ID or name of the request queue to be opened. If a string is provided, it will first be looked up as an ID; if no such storage exists, it will be treated as a name. If null or undefined, the function returns the default request queue associated with the crawler run.

    • externaloptionaloptions: StorageOpenOptions

      Open Request Queue options.

    Returns Promise<RequestQueue>

Page Options