Generating links into Pivot

This information applies to on-prem Pivot instances only.

You can generate links that open to specific views from external systems by POSTing to /api/v1/mkurl.

The post body must include two keys:

# domain (string)

The domain on which Imply is running. It will simply be prefixed to the URL.

# essence (Essence)

The essence JSON that describes the state. The best way to understand what goes here is to see what calls the UI makes to /api/v1/mkurl/register, which utilizes the same mechanism described here to do URL shortening.

// generating a link
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "domain": <domain name>,
  "essence": {<essence object>}
}
' localhost:9095/api/v1/mkurl

Examples:

input:

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:ea750788-9ee5-4498-b2eb-ea25d7a62af5" --data '{
  "domain": "http://localhost:9095",
  "essence": {
    "dataCube": "wikipedia",
    "timezone": "Etc/UTC",
    "filter": {
      "clauses": [
        {
          "dimension": "__time",
          "dynamic": {
            "op": "timeRange",
            "operand": {
              "op": "ref",
              "name": "m"
            },
            "duration": "P1D",
            "step": -1
          }
        }
      ]
    },
    "splits": [],
    "selectedMeasures": ["count"],
    "pinnedDimensions": ["page"],
    "visualization": "totals"
  }
}' localhost:9095/api/v1/mkurl

output:

{ "url": "http://localhost:9095/pivot/d/63af9c7492ddc2273b/Wikipedia" }

More examples for Essence

Example 1

Here is an example that will show the totals visualization filtered dynamically on the last day with the count measure selected and the page dimension pinned.

{
  "domain": "http://localhost:9095",
  "essence": {
    "dataCube": "wikipedia",
    "timezone": "Etc/UTC",
    "filter": {
      "clauses": [
        {
          "dimension": "__time",
          "dynamic": {
            "op": "timeRange",
            "operand": {
              "op": "ref",
              "name": "m"
            },
            "duration": "P1D",
            "step": -1
          }
        }
      ]
    },
    "splits": [],
    "selectedMeasures": ["count"],
    "pinnedDimensions": ["page"],
    "visualization": "totals"
  }
}

Posting this will produce:

{
  "url": "http://localhost:9095/pivot/d/63af9c7492ddc2273b/Wikipedia"
}

Example 2

Here is an example that will show the line-chart visualization filtered on the last 3 days of data (P3D), split on time (bucketed by hour - PT1H), with count, added, deleted, and delta measures selected.

{
  "domain": "http://localhost:9095",
  "essence": {
    "dataCube": "wikipedia",
    "visualization": "line-chart",
    "timezone": "Etc/UTC",
    "filter": {
      "clauses": [
        {
          "dimension": "__time",
          "dynamic": {
            "op": "timeRange",
            "operand": {
              "op": "ref",
              "name": "m"
            },
            "duration": "P1D",
            "step": -3
          }
        }
      ]
    },
    "splits": [
      {
        "dimension": "__time",
        "bucketAction": {
          "op": "timeBucket",
          "duration": "PT1H"
        }
      }
    ],
    "selectedMeasures": ["count", "added", "deleted", "delta"],
    "pinnedDimensions": []
  }
}

Posting this will produce:

{
  "url": "http://localhost:9095/pivot/d/2a9e32bb756240a298/Wikipedia"
}

Note: the $m variable represents maxTime - the timestamp of the latest data point. In contrast, $n represents 'now'.

Example 3

Here is an example that will also select some dimension filters:

{
  "domain": "http://localhost:9095",
  "essence": {
    "dataCube": "wikipedia",
    "timezone": "Etc/UTC",
    "filter": {
      "clauses": [
        {
          "dimension": "__time",
          "values": {
            "setType": "TIME_RANGE",
            "elements": [
              {
                "start": "2016-06-27T04:00:00.000Z",
                "end": "2016-06-27T18:00:00.000Z"
              }
            ]
          }
        },
        {
          "dimension": "channel",
          "action": "overlap",
          "values": {
            "setType": "STRING",
            "elements": [
              "#en.wikipedia",
              "#sh.wikipedia"
            ]
          }
        }
      ]
    },
    "splits": [
      {
        "dimension": "page",
        "sortType": "measure",
        "direction": "descending"
      }
    ],
    "selectedMeasures": ["count"],
    "pinnedDimensions": ["user"],
    "visualization": "table"
  }
}

Posting this will produce:

{
  "url": "http://localhost:9095/pivot/d/eaf8d548a39f9776e3/Wikipedia"
}