zoomdata-client

Zoomdata Javascript SDK

[DEPRECATED]

This package is deprecated since Composer 7.10 release and will not be maintained starting 8.0. It is recommended to use Embed Manager as a replacement.

---

Trusted Access Tokens

The Zoomdata Javascript SDK requires a user's trusted access token to connect to a Zoomdata Server. For information on Trusted Access, its prerequisites, and generating user based tokens, please visit the Trusted Access Documentation

Install the library

npm install zoomdata-client

zoomdata-client comes built as an UMD. You are able to use it both in a browser from node_modules:

<script src="node_modules/zoomdata-client/sdk/zoomdata-client.js" type="text/javascript"></script>

or in a browser served from your Zoomdata server (update the URL accordingly):

<script src="https://localhost:8443/composer/sdk/zoomdata-client.js" type="text/javascript"></script>

or as a commonJS module:

var ZoomdataSDK = require('zoomdata-client');

Create a Client

When instantiating a Zoomdata JS client, you need to supply connection properties as well as an authentication trusted access token. The .createClient function returns a Javascript Promise that resolves to the client.

var credentials = {
    access_token: TRUSTED_ACCESS_TOKEN,
};

var application = {
    secure: false,
    host: 'localhost',
    port: 8080,
    path: '/composer',
};

ZoomdataSDK.createClient({
    credentials: credentials,
    application: application,
}).then(function (client) {
    console.log('Validated:', client);
});

Create a Query

When creating a Query, you need to supply a Data Source name as well as a query configuration.

The .createQuery function returns a Javascript Promise that resolves to the validated Query.

client.createQuery(
    { id: 'source_id' },
    {
        filters: [],
        groups: [
            {
                name: 'userincome',
                limit: 10,
                sort: {
                    dir: 'asc',
                    name: 'userincome',
                },
            },
        ],
        metrics: [],
    },
);

Query Configuration Details

A Query can be Grouped or Ungrouped.

An Ungrouped Query only requires an array of fields. This configuration will return all records with just the userincome and usergender fields.

{
    fields: ['userincome, usergender'];
}

A Grouped Query requires an array of Groupings. Optionally, you can include an array of Metrics. This configuration will group by the userincome field and calculate the average of the usersentiment field.

{
    groups: [{
        name: 'userincome',
        limit: 10,
        sort: {
            dir: 'asc',
            name: 'usergender'
        }
    }],
    metrics: [{
        name: 'usersentiment',
        func: 'avg'
    }]
}

All Queries can include an optional array of filters. This configuration will filter only results with a usersentiment between -0.5 and 0.5.

{
    filters: [
        {
            path: 'usersentiment',
            operation: 'BETWEEN',
            value: [-0.5, 0.5],
        },
    ];
}

Run a Query

When running a Query, you must provide a callback that receives new data as it arrives from the Zoomdata Server.

client.runQuery(query, function (data) {
    console.log(data);
});

Embed a Chart

When embedding a Chart, you must provide an HTML element to embed the chart into, a query to run for the chart, the name of the visualization, and an object for overriding Chart Variables.

Note: You can find variable names and values in your Zoomdata Server's Source Configuration Page.

var variables = {
    Size: 'count',
};

client.visualize({
    element: document.body,
    query: query,
    visualization: 'Donut',
    variables: variables,
});

Example

var credentials = {
    access_token: TRUSTED_ACCESS_TOKEN,
};

var application = {
    secure: false,
    host: 'localhost',
    port: 8080,
    path: '/zoomdata',
};

var variables = {
    Size: [{ name: 'count' }],
};

ZoomdataSDK.createClient({
    credentials: credentials,
    application: application,
})
    .then(function (client) {
        client
            .createQuery(
                { name: 'Real Time Sales' },
                {
                    filters: [],
                    groupBy: [
                        {
                            name: 'userincome',
                            limit: 10,
                        },
                    ],
                    metrics: [],
                },
            )
            .then(function (query) {
                client.runQuery(query, function (data) {
                    console.log(data);
                });

                client
                    .visualize({
                        element: document.body,
                        query: query,
                        visualization: 'Donut',
                        variables: variables,
                    })
                    .catch(onError);
            })
            .catch(onError);
    })
    .catch(onError);

function onError(reason) {
    console.error(reason.stack || reason.statusText || reason);
}

Licensing

Zoomdata Javascript SDK is licensed under the terms of the Zoomdata EULA.

See the LICENSE file for further information.