Insight

Insights: run, copy, and read insight data.

Endpoints

Endpoint	Arguments	Returns
v3.insight.copy	insightId: string, options: { name: string }	unknown
v3.insight.create	WorkspaceId, options	object
v3.insight.data	insightId: string, options?: { update?: boolean }	object
v3.insight.list	cid: string	object[]
v3.insight.member.add	insightId: string, permissionItem: string	boolean
v3.insight.member.remove	insightId: string, permissionItem: string	boolean
v3.insight.preview	workspaceId: string, input: { query: string, sources: InsightSource[] }	object
v3.insight.public	insightKey: string	object
v3.insight.remove	insightId: string	unknown
v3.insight.update	insightId: string, update: object	object

v3.insight.copy

Description

Copy an insight with a new name

Parameters

Argument 1 (ObjectId, required): insightId

Argument 2 (object, required):

Field	Type	Required	Description
name	string	no	Visible name

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.copy', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  {
    name: 'string', // Visible name
  },
]);
console.log(result);

Returns

Undocumented

The return value is not described in the source yet.

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.create

Description

Create a new insight with data sources and SQL query for analytics and reporting.

Parameters

Argument 1 (WorkspaceId, required): workspaceId (former networkId)

Argument 2 (object, optional):

Field	Type	Required	Description
name	string	yes	Visible name
public	boolean	no	Enable Insight data to be fetched via v3.insight.public endpoint publicly Default: false.
sources	object[]	yes	Tables in SQL
query	string	yes	SQLite query string to work on the temporary tables built from sources

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.create', [
  '507f1f77bcf86cd799439011', // WorkspaceId (required)
  {
    name: 'string', // Visible name
    sources: [{
      name: 'string', // Table name in SQL
      workflowId: '507f1f77bcf86cd799439011', // Workflow or Dataset Id to get activities from
      fields: [{ /* ... */ }], // Columns in SQL, set `fieldId` or `meta` as data mapping
    }], // Tables in SQL
    query: 'string', // SQLite query string to work on the temporary tables built from sources
  },
]);
console.log(result);

Returns

Field	Type	Required	Description
_id	ObjectId	yes	insightId
hash	binary	no
created	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
updated	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
uid	userId	yes	userId
cid	WorkspaceId	yes	workspaceId (former networkId)
members	object[]	yes
name	string	yes	Visible name
description	string	no
public	boolean	yes	Enable Insight data to be fetched via v3.insight.public endpoint publicly
publicKey	string	yes	Key used to access insight when public is set to true
sources	object[]	yes	Tables in SQL
query	string	yes	SQLite query string to work on the temporary tables built from sources
presets	object[]	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.data

Description

Execute insight query and return data results for analytics visualization.

Parameters

Argument 1 (ObjectId, required): insightId

Argument 2 (Option, optional):

Field	Type	Required	Description
update	boolean	no	Ignore cached data, and force to rebuild

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.data', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  {
    update: false, // Ignore cached data, and force to rebuild
  },
]);
console.log(result);

Returns

Field	Type	Required	Description
headers	string[]	yes
rows	string[][]	yes	Rows of data
time	timestamp	yes	Timestamp when data was last updated

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.list

Description

List all insights in a workspace that the user has access to

Parameters

Argument 1 (WorkspaceId, required): workspaceId (former networkId)

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.list', [
  '507f1f77bcf86cd799439011', // WorkspaceId (required)
]);
console.log(result);

Returns

Array of objects:

Field	Type	Required	Description
_id	ObjectId	yes	insightId
created	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
updated	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
uid	userId	yes	userId
cid	WorkspaceId	yes	workspaceId (former networkId)
members	object[]	yes
name	string	yes	Visible name
description	string	no
public	boolean	yes	Enable Insight data to be fetched via v3.insight.public endpoint publicly
publicKey	string	yes	Key used to access insight when public is set to true
sources	object[]	yes	Tables in SQL
query	string	yes	SQLite query string to work on the temporary tables built from sources
presets	object[]	no
hash	any	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.member.add

Description

Add member

Parameters

Argument 1 (ObjectId, required): insightId

Argument 2 (string, required): network_<networkId>, team_<teamId>, user_<userId>, group_<groupId>

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.member.add', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  'string', // `network_<networkId>`, `team_<teamId>`, `user_<userId>`, `group_<groupId>` (required)
]);
console.log(result);

Returns

boolean

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.member.remove

Description

Remove member of process.

Parameters

Argument 1 (ObjectId, required): insightId

Argument 2 (string, required): network_<networkId>, team_<teamId>, user_<userId>, group_<groupId>

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.member.remove', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  'string', // `network_<networkId>`, `team_<teamId>`, `user_<userId>`, `group_<groupId>` (required)
]);
console.log(result);

Returns

boolean

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.preview

Description

Preview insight query execution before saving - test data sources and SQL queries.

Parameters

Argument 1 (WorkspaceId, required): workspaceId (former networkId)

Argument 2 (object, optional):

Field	Type	Required	Description
query	string	yes	SQLite query string to work on the temporary tables built from sources
sources	object[]	yes	Tables in SQL

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.preview', [
  '507f1f77bcf86cd799439011', // WorkspaceId (required)
  {
    query: 'string', // SQLite query string to work on the temporary tables built from sources
    sources: [{
      name: 'string', // Table name in SQL
      workflowId: '507f1f77bcf86cd799439011', // Workflow or Dataset Id to get activities from
      fields: [{ /* ... */ }], // Columns in SQL, set `fieldId` or `meta` as data mapping
    }], // Tables in SQL
  },
]);
console.log(result);

Returns

Field	Type	Required	Description
headers	string[]	yes
rows	string[][]	yes	Rows of data
details	Record<string, object>	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.public

Description

Get public insight data by insight key

Parameters

Argument 1 (string, required): insightKey

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.public', [
  'string', // insightKey (required)
]);
console.log(result);

Returns

Field	Type	Required	Description
insight	object	no
data	object	no

Auth: callable without authentication.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.remove

Description

Remove an insight

Parameters

Argument 1 (ObjectId, required): insightId

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.remove', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Undocumented

The return value is not described in the source yet.

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.insight.update

Description

Update an existing insight

Parameters

Argument 1 (ObjectId, required): insightId

Argument 2 (object, required):

Field	Type	Required	Description
name	string	no	Visible name
public	boolean	no	Enable Insight data to be fetched via v3.insight.public endpoint publicly
sources	object[]	no	Tables in SQL
query	string	no	SQLite query string to work on the temporary tables built from sources
presets	object[]	no

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.insight.update', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  {
    name: 'string', // Visible name
    public: false, // Enable Insight data to be fetched via `v3.insight.public` endpoint publicly
  },
]);
console.log(result);

Returns

Field	Type	Required	Description
_id	ObjectId	yes	insightId
hash	binary	no
created	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
updated	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
uid	userId	yes	userId
cid	WorkspaceId	yes	workspaceId (former networkId)
members	object[]	yes
name	string	yes	Visible name
description	string	no
public	boolean	yes	Enable Insight data to be fetched via v3.insight.public endpoint publicly
publicKey	string	yes	Key used to access insight when public is set to true
sources	object[]	yes	Tables in SQL
query	string	yes	SQLite query string to work on the temporary tables built from sources
presets	object[]	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.