Skip to main content
Version: 0.16

Remote

Remote lookup lists retrieve key-value pairs from an external source over HTTP, allowing lookup data to be managed centrally and refreshed periodically. Two formats are supported: a simple list format where each entry occupies a single line, and CSV for more structured data.

Each list is associated with a refresh interval and a retry interval. Once the refresh interval elapses, the server automatically re-fetches the list so that values remain current without manual intervention.

Configuration​

Remote lookup lists are defined through the HttpLookup object (found in the WebUI under Settings › Lookups › HTTP Lists). Each record has the following fields:

  • url: HTTP endpoint from which the list is fetched (required).
  • enable: when true, the list is active. Default: true.
  • format: format of the remote list (required). Two variants are supported: List (one entry per line) and Csv (comma-separated values with configurable parsing).
  • isGzipped: when true, the payload is decompressed with gzip before parsing. Default: false.
  • refresh: how often to re-fetch the list. Default: "12h".
  • retry: how long to wait before retrying a failed fetch. Default: "1h".
  • timeout: maximum time allowed for the fetch operation. Default: "30s".
  • namespace: the namespace under which the list's entries are exposed to lookup functions (read-only; derived from the record identifier).

CSV parsing options​

When format is set to the Csv variant, the variant carries additional fields:

  • separator: the delimiter between columns. Default: ",".
  • indexKey: zero-based column index used as the lookup key. Default: 0.
  • indexValue: optional zero-based column index used as the lookup value.
  • skipFirst: when true, the first line is treated as a header and skipped. Default: false.

Resource limits​

The size of the retrieved list and each of its entries is bounded by:

  • maxSize: maximum total size of the list in bytes. Default: "100mb".
  • maxEntries: maximum number of entries retained. Default: 100000.
  • maxEntrySize: maximum size of a single entry in bytes. Default: 512.

The list is truncated if it exceeds any of these limits.