Skip to main content
Version: Next

KeyValueStore

@inheritDoc

Hierarchy

  • KeyValueStore
    • KeyValueStore

Index

Properties

Methods

Properties

externalreadonlyconfig

config: Configuration

externalreadonlyid

id: string

externaloptionalreadonlyname

name?: string

Methods

externaldrop

  • drop(): Promise<void>

  • Removes the key-value store either from the Apify cloud storage or from the local directory, depending on the mode of operation.

    Returns Promise<void>

externalforEachKey

  • Iterates over key-value store keys, yielding each in turn to an iteratee function. Each invocation of iteratee is called with three arguments: (key, index, info), where key is the record key, index is a zero-based index of the key in the current iteration (regardless of options.exclusiveStartKey) and info is an object that contains a single property size indicating size of the record in bytes.

    If the iteratee function returns a Promise then it is awaited before the next call. If it throws an error, the iteration is aborted and the forEachKey function throws the error.

    Example usage

    const keyValueStore = await KeyValueStore.open();
    await keyValueStore.forEachKey(async (key, index, info) => {
      console.log(`Key at ${index}: ${key} has size ${info.size}`);
    });

    Parameters

    Returns Promise<void>

externalgetAutoSavedValue

  • getAutoSavedValue<T>(key: string, defaultValue?: T): Promise<T>

  • Type parameters

    • T: Dictionary = Dictionary

    Parameters

    • externalkey: string
    • externaloptionaldefaultValue: T

    Returns Promise<T>

getPublicUrl

  • getPublicUrl(key: string): string

  • Returns a URL for the given key that may be used to publicly access the value in the remote key-value store.

    Parameters

    • key: string

    Returns string

externalgetValue

  • getValue<T>(key: string): Promise<null | T>
  • getValue<T>(key: string, defaultValue: T): Promise<T>

  • Gets a value from the key-value store.

    The function returns a Promise that resolves to the record value, whose JavaScript type depends on the MIME content type of the record. Records with the application/json content type are automatically parsed and returned as a JavaScript object. Similarly, records with text/plain content types are returned as a string. For all other content types, the value is returned as a raw Buffer instance.

    If the record does not exist, the function resolves to null.

    To save or delete a value in the key-value store, use the KeyValueStore.setValue function.

    Example usage:

    const store = await KeyValueStore.open();
    const buffer = await store.getValue('screenshot1.png');

    Type parameters

    • T = unknown

    Parameters

    • externalkey: string

      Unique key of the record. It can be at most 256 characters long and only consist of the following characters: a-z, A-Z, 0-9 and !-_.'()

    Returns Promise<null | T>

    Returns a promise that resolves to an object, string or Buffer, depending on the MIME content type of the record.

externalrecordExists

  • recordExists(key: string): Promise<boolean>

  • Tests whether a record with the given key exists in the key-value store without retrieving its value.

    Parameters

    • externalkey: string

      The queried record key.

    Returns Promise<boolean>

    true if the record exists, false if it does not.

externalsetValue

  • setValue<T>(key: string, value: null | T, options?: RecordOptions): Promise<void>

  • Saves or deletes a record in the key-value store. The function returns a promise that resolves once the record has been saved or deleted.

    Example usage:

    const store = await KeyValueStore.open();
    await store.setValue('OUTPUT', { foo: 'bar' });

    Beware that the key can be at most 256 characters long and only contain the following characters: a-zA-Z0-9!-_.'()

    By default, value is converted to JSON and stored with the application/json; charset=utf-8 MIME content type. To store the value with another content type, pass it in the options as follows:

    const store = await KeyValueStore.open('my-text-store');
    await store.setValue('RESULTS', 'my text data', { contentType: 'text/plain' });

    If you set custom content type, value must be either a string or Buffer, otherwise an error will be thrown.

    If value is null, the record is deleted instead. Note that the setValue() function succeeds regardless whether the record existed or not.

    To retrieve a value from the key-value store, use the KeyValueStore.getValue function.

    IMPORTANT: Always make sure to use the await keyword when calling setValue(), otherwise the crawler process might finish before the value is stored!

    Type parameters

    • T

    Parameters

    • externalkey: string

      Unique key of the record. It can be at most 256 characters long and only consist of the following characters: a-z, A-Z, 0-9 and !-_.'()

    • externalvalue: null | T

      Record data, which can be one of the following values:

      • If null, the record in the key-value store is deleted.
      • If no options.contentType is specified, value can be any JavaScript object and it will be stringified to JSON.
      • If options.contentType is set, value is taken as is and it must be a String or Buffer. For any other value an error will be thrown.
    • externaloptionaloptions: RecordOptions

      Record options.

    Returns Promise<void>

staticexternalgetAutoSavedValue

  • getAutoSavedValue<T>(key: string, defaultValue?: T): Promise<T>

  • Type parameters

    • T: Dictionary = Dictionary

    Parameters

    • externalkey: string
    • externaloptionaldefaultValue: T

    Returns Promise<T>

staticopen

  • open(storeIdOrName?: null | string, options?: StorageManagerOptions): Promise<KeyValueStore>
  • @inheritDoc

    Parameters

    • optionalstoreIdOrName: null | string
    • options: StorageManagerOptions = {}

    Returns Promise<KeyValueStore>

staticexternalrecordExists

  • recordExists(key: string): Promise<boolean>

  • Tests whether a record with the given key exists in the default KeyValueStore associated with the current crawler run.

    Parameters

    • externalkey: string

      The queried record key.

    Returns Promise<boolean>

    true if the record exists, false if it does not.

Page Options