You are currently browsing legacy 4.0 version of documentation. Click here to switch to the newest 6.2 version.
    We can help you with migration to the latest RavenDB
    Contact Us Now
    See on GitHub

    Data Subscriptions: Consumption API Overview

    In this page:

    Subscription worker generation
    SubscriptionWorkerOptions
    Running subscription worker
    SubscriptionBatch<T>
    SubscriptionWorker<T>

    Subscription worker generation

    Subscription worker generation is accessible through the DocumentStore's subscriptions property, of type DocumentSubscriptions: 

    store.subscriptions.getSubscriptionWorker(options, [database]);
store.subscriptions.getSubscriptionWorker(subscriptionName, [database]);

store.subscriptions.getSubscriptionWorkerForRevisions(options, [database]);
store.subscriptions.getSubscriptionWorkerForRevisions(subscriptionName, [database]);
    Parameters
    subscriptionName string The subscription's name. This parameter appears in more simple overloads allowing to start processing without creating a SubscriptionCreationOptions instance, relying on the default values
    options SubscriptionWorkerOptions Contains subscription worker, affecting the interaction of the specific worker with the subscription, but does not affect the subscription's definition
    subscriptionName string Returns the subscription name passed to the constructor. This name will be used by the server side to identify the subscription in question.
    timeToWaitBeforeConnectionRetry number Time to wait before reconnecting, in the case of non-aborting failure during the subscription processing. Default: 5 seconds.
    ignoreSubscriberErrors boolean If true, will not abort subscription processing if client code, passed to the run function, throws an unhandled exception. Default: false.
    strategy SubscriptionOpeningStrategy(enum) Sets the way the server will treat current and/or other clients when they will try to connect. See Workers interplay. Default: OPEN_IF_FREE.
    maxDocsPerBatch number Maximum amount of documents that the server will try sending in a batch. If the server will not find "enough" documents, it won't wait and send the amount it found. Default: 4096.
    closeWhenNoDocsLeft boolean If true, it performs an "ad-hoc" operation that processes all possible documents, until the server can't find any new documents to send. An error of type SubscriptionClosedException is going to be emitted. Default: false.
    database string Name of the database to look for the data subscription. If null, the default database configured in DocumentStore will be used.
    Return value
    SubscriptionWorker A created data subscription worker.

    {PANEL:Running subscription worker}

    After obtaining a subscription worker instance, it's going to connect asynchronously when the "batch" event listener is registered. Once connected it's going to emit events allowing the user to process batches and handle errors.

    subscriptionWorker.on("batch", (batch, callback) => { });
subscriptionWorker.on("error", (error) => {});
subscriptionWorker.on("end", () => {});

    SubscriptionBatch

    Member Type Description
    items SubscriptionBatchItem Batch's items list.
    numberOfItemsInBatch number Amount of items in the batch.

    SubscriptionBatchItem

    Member Type Description
    result object Current batch item.
    exceptionMessage string Message of the exception thrown during current document processing in the server side.
    id string Current batch item's underlying document ID.
    changeVector string Current batch item's underlying document change vector of the current document.
    rawResult object Current batch item - no types revived.
    rawMetadata object Current batch item's underlying document metadata.
    metadata object Current batch item's underlying metadata values.

    SubscriptionWorker

    Methods

    Method Signature Return Type Description
    dispose() void Aborts subscription worker operation.

    Events

    Events Listener signature
    "batch" (batch, callback) => void Client-side batch processing. Once processing is done, callback must be called in order to continue batches' emission.
    "error" (error) => void Emitted on subscription errors
    "connectionRetry" (error) => void Emitted on connection retry.
    "end" (error) => void Emitted when subscription is finished. No more batches are going to be emitted.

    Properties

    Member Type\Return type Description
    currentNodeTag string Returns current processing RavenDB server's node tag.
    subscriptionName string Returns processed subscription's name.

    related articlesRelated Articles

    Data Subscriptions:

    Home / Docs / Client Api / Data Subscriptions / Consumption / Api Overview