Skip to main content

Using IR and Ingest

IR is a command-line tool that uses Informer API calls to automate tasks that Jobs cannot. Because it works over the API, it does not have to run on the Informer server: it can run from any machine that can reach Informer's login page.

Install IR​

IR is a Node.js application hosted in the Informer repository, so a docker.entrinsik.com user is required. On the machine that will run IR:

  1. Install Node.js if it is not already installed. IR supports Node.js version 22. The commands run in a Linux terminal or a Windows PowerShell window.

  2. Log in to the repository, entering your docker.entrinsik.com credentials when prompted:

    npm config set registry https://docker.entrinsik.com/repository/npm/
    npm adduser --registry https://docker.entrinsik.com/repository/npm/

  3. Install IR:

    npm install -g @entrinsik/ir

  4. Confirm the installation:

    ir --version

Get help within IR​

IR has built-in help. List what IR can interact with:

ir help

Get details on a topic or command, replacing <command> with the topic or command:

ir <command> --help

For example, to get help logging in:

ir login --help

Log in to Informer with IR​

IR can remember multiple sessions to the same or different Informer instances, which is helpful for partners or consultants working across environments. List the sessions:

ir sessions

Switch to an existing session, replacing <session-name> with a name from the list:

ir su <session-name>

Check the current session:

ir whoami

IR can sign in several ways, but the preferred method is a full read/write API token (see API Tokens). Log in with a token, replacing the placeholders with your values:

ir login --url <url> --tenant <tenant> --token <token> --name <new-session>

For example:

ir login --url https://test.informer.cloud --tenant example --token <token> --name test

Use IR Ingest​

IR Ingest calls a Dataset refresh many times in succession with different inputs each time. It is ideal for loading historical data into a large Dataset that uses Append or Upsert mode. It is typically run once per Dataset, after which the Dataset should refresh on a Job.

Ingest needs a JSON file, plan.json, describing the refresh plan: the Dataset ID, the Inputs, and the values to pass through them. For example:

{
  "defaults": {
    "tenant": ["my-tenant-name"]
  },
  "datasets": {
    "owner:dataset-slug": {
      "params": {
        "aliasOfDateInput.start": "${start.slice(0,10)}",
        "aliasOfDateInput.end": "${end.slice(0,10)}"
      },
      "interval": "P1M",
      "start": "2010-01-01",
      "end": "2025-12-31"
    }
  }
}

In this example, the Dataset needs a Date Range Input with the alias aliasOfDateInput. The plan tells Ingest to run refreshes from 2010 to 2025 broken into one-month intervals, so IR refreshes the Dataset 180 times. This is more stable than refreshing once with a large amount of data.

Run the plan in these steps:

  1. Clear the existing Ingest queue:

    ir ingest:delete --all

  2. Load the plan file, replacing <plan.json> with your file:

    ir ingest:load -f <plan.json>

  3. Optionally, list the queued Ingest tasks to review the upcoming refreshes:

    ir ingest:list --all

  4. Start the Ingest so an Ingest server can pick it up:

    ir ingest:start

  5. Optionally, start a monitor to watch the Ingest server:

    ir ingest:monitor

  6. Start the Ingest server to make the API calls. Use --workers to set how many concurrent requests run; a higher value finishes faster but uses more resources on the Informer server (default 10):

    ir ingest:server -v --workers=4
    Run the server and monitor separately

    The ingest:server command must run in a different terminal from the ingest:monitor command.

Other commands​

IR has many other commands. Use the built-in ir help and ir <command> --help to see what else is available.