Looker SDK for Node

The Looker SDK for TypeScript/JavaScript works with Node and browser run-times. The SDK provides a convenient way to communicate with a Looker server's APIs.

This package is specifically for using the Looker TypeScript SDK with Node. It depends on the @looker/sdk package and @looker/sdk-rtl.

The SDK uses a plug-in architecture (also known as dependency injection) for initializing that supports run-time specific transports (like NodeTransport and BrowserTransport) and different approaches for managing API authentication (like NodeSession, BrowserSession, ProxySession, and OauthSession).

Please report any issues encountered, and indicate the SDK language in the report.

Getting started

The Looker SDK can be used in a node application in 3 steps:

• install
• configure
• use

Install the Looker SDK into your node application

Using yarn:

yarn add @looker/sdk @looker/sdk-rtl @looker/sdk-node

Using npm:

npm install @looker/sdk @looker/sdk-rtl @looker/sdk-node

Note: If you are only intending to use the SDK in a browser, omit @looker/sdk-node.

Some other dependencies may be required for your project to build and run correctly.

TypeScript SDK packages

The Looker TypeScript SDK has different packages to prevent node dependencies being linked into browser usage of the SDK (the node dependencies are not available in the browser and can cause compilation errors). There are three packages for the Typescript SDK available on npm:

1. @looker/sdk-rtl - contains a run time library needed to invoke the Looker API methods. Referencing the @looker/sdk as a dependency should automatically pull this package in.
2. @looker/sdk - contains the Looker API methods.
3. @looker/sdk-node - contains the dependencies needed to run the Looker SDK in a node environment. Do NOT include this package if you are using the Looker SDK in a browser. You MUST include this package if you are using node or ts-node.

Configure the SDK for your Looker server

Note: The .ini configuration for the Looker SDK is a sample implementation intended to speed up the initial development of Node applications using the Looker API. Environment variables can also be used to configure the SDK.

Create a looker.ini file with your server URL and API credentials assigned as shown below:

[Looker]
# Base URL for API. Do not include /api/* in the url
base_url=https://<your-looker-server>:19999
# API 3 client id
client_id=your_API3_client_id
# API 3 client secret
client_secret=your_API3_client_secret

Note: If the application using the Looker SDK is going to be committed to a version control system, be sure to ignore the looker.ini file to avoid publishing your API credentials.

Note: The Browser SDK does not use a looker.ini or environment variables.

Use the SDK in your code

When the SDK is installed and the server location and API credentials are configured in your looker.ini file, it's ready to be used.

Verify authentication works and that API calls will succeed with code similar to the following:

import { LookerNodeSDK } from '@looker/sdk-node'
(async () => {
  // create a Node SDK object for API 4.0
  const sdk = LookerNodeSDK.init40()
  // retrieve your user account to verify correct credentials
  const me = await sdk.ok(sdk.me(
    "id, first_name, last_name, display_name, email, personal_space_id, home_space_id, group_ids, role_ids"))
  console.log({me})
  // make any other calls to the Looker SDK
  const dashboards = await sdk.ok(
    sdk.search_dashboards({title: 'My SDK dashboard'})
  )
  if (dashboards.length === 0) {
    console.log('Dashboard not found')
  }
  const [ dashboard ] = dashboards
  // do stuff with dashboard

  ...

  await sdk.authSession.logout()
  if (!sdk.authSession.isAuthenticated()) {
    console.log('Logout successful')
  }
})()

NOTE: By default, LookerNodeSDK.init40() will check for environment variables. Environment variables can be ignored by passing an empty string to the NodeSettings constructor.

// Ignore any SDK environment variables for the node runtime
const settings = new NodeSettingsIniFile('');
const sdk = LookerNodeSDK.init40(settings);

Developing with multiple API versions

Starting with Looker release 23.18, API 3.1 and 3.0 have been removed. Please use the stable and current version API 4.0 as shown below.

LookerNodeSDK.init40() LookerBrowserSDK.init40() and Looker40SDK() all initialize the API 4.0 implementation of the SDK.

Using NodeSession for automatic authentication

Almost all requests to Looker's API require an access token. Typically, this token is established when the login endpoint is called with correct API3 credentials for client_id and client_secret. When login is successful, the provided API3 credentials are used to look up the active API user.

The settings provided to the NodeSession class include the base URL for the Looker instance, and the desired API version. When API requests are made, if the auth session is not yet established, NodeSession will automatically authenticate the API User.

Sudo behavior with NodeSession

NodeSession also directly supports logging in as another user, which is usually called sudo as another user in the Looker browser application.

An API user with appropriate permissions can sudo as another user by passing a different user ID to the NodeSession.login() method. Only one user can be impersonated at a time via NodeSession. When a sudo session is active, all SDK requests are processed as that user.

The test below shows use cases for authentication and sudo. This code sample is extracted directly from the sdk methods functionla tests, and assumes apiUser is the default authenticated user record with sudo abilities, and sudoA and sudoB are other enabled Looker user accounts.

describe('sudo', () => {
  it(
    'login/logout',
    async () => {
      const sdk = new LookerSDK(session);
      const apiUser = await sdk.ok(sdk.me());
      let all = await sdk.ok(
        sdk.all_users({
          fields: 'id,is_disabled',
        })
      );

      // find users who are not the API user
      const others = all
        .filter(u => u.id !== apiUser.id && !u.is_disabled)
        .slice(0, 2);
      expect(others.length).toEqual(2);
      if (others.length > 1) {
        // pick two other active users for `sudo` tests
        const [sudoA, sudoB] = others;
        // get auth support for login()
        const auth = sdk.authSession as IAuthSession;

        // login as sudoA
        await auth.login(sudoA.id.toString());
        let sudo = await sdk.ok(sdk.me()); // `me` returns `sudoA` user
        expect(sudo.id).toEqual(sudoA.id);

        // login as sudoB directly from sudoA
        await auth.login(sudoB.id);
        sudo = await sdk.ok(sdk.me()); // `me` returns `sudoB` user
        expect(sudo.id).toEqual(sudoB.id);

        // logging out sudo resets to API user
        await auth.logout();
        let user = await sdk.ok(sdk.me()); // `me` returns `apiUser` user
        expect(sdk.authSession.isAuthenticated()).toEqual(true);
        expect(user).toEqual(apiUser);

        // login as sudoA again to test plain `login()` later
        await auth.login(sudoA.id);
        sudo = await sdk.ok(sdk.me());
        expect(sudo.id).toEqual(sudoA.id);

        // login() without a sudo ID logs in the API user
        await auth.login();
        user = await sdk.ok(sdk.me()); // `me` returns `apiUser` user
        expect(sdk.authSession.isAuthenticated()).toEqual(true);
        expect(user.id).toEqual(apiUser.id);
      }
      await sdk.authSession.logout();
      expect(sdk.authSession.isAuthenticated()).toEqual(false);
    },
    testTimeout
  );
});

Environment variable configuration

Environment variables can be used to configure access for the Node version of the Looker SDK.

Once the desired environment variables are set, the following code is all that's required to initialize the Looker SDK and retrieve the API credential's User information.

const sdk = LookerNodeSDK.init40(new NodeSettings());
const me = await sdk.ok(sdk.me());

Streaming with the SDK

The deprecated NodeJS request package dependency has been removed from all Looker TypeScript packages. This removal prompted a BREAKING interface change for the streaming SDK. The streaming method callback signature changed from (readable: Readable) => Promise<x> to (response: Response) => Promise<x>. Using Response as the parameter to the callback greatly increases the flexibility of streaming implementations and provides other valuable information like Content-Type and other headers to the streaming callback.

For the Browser SDK (@looker/sdk), the standard fetch function is still used. For the Node SDK (@looker/sdk-node), the global fetch function from NodeJS is used, which was marked stable in version 22.

This means the Looker Node SDK now requires Node 20 or above.

The streaming version of the SDK methods should be initialized using the same AuthSession as the main SDK to reduce authentication thrashing.

Construction of the streaming SDK can use code similar to the following, which is taken from the downloadTile.ts example:

/**
 * Use the streaming SDK to download a tile's query
 * @param sdk to use
 * @param tile to download
 * @param format to download
 * @returns name of downloaded file (undefined on failure)
 */
const downloadTileAs = async (
  sdk: LookerSDK,
  tile: IDashboardElement,
  format: string
) => {
  const fileName = `${tile.title}.${format}`;

  const writer = createWritableStream(fs.createWriteStream(fileName));
  const request: IRequestRunQuery = {
    result_format: format,
    query_id: tile.query_id!,
    // apply_formatting: true,
    // apply_vis: true
  };
  const sdkStream = new Looker40SDKStream(sdk.authSession);
  await sdkStream.run_query(async (response: Response) => {
    await response.body.pipeTo(writer);
    return 'streamed';
  }, request);

  return fileName;
};

More examples

See the SDK Examples folder for additional TypeScript SDK examples.

A note about security

Any script or configuration file used to provide credentials to your Looker SDK instance needs to be secured.