Skip to main content

Guide for analyzing data

This guide walks through the end-to-end process to ingest data into Imply Polaris and analyze it using the following Polaris APIs:

The following diagram summarizes the process of ingesting and analyzing data in this guide.

Prerequisites​

Before you complete the steps in this guide, ensure that you have the following:

  • A Polaris API key with the following permissions:

    AdministerAlerts
    AdministerDashboards
    AdministerDataCubes
    AdministerEmbedLinks
    AdministerReports
    ManageIngestionJobs
    ManageTables

    In the API requests in this guide, the API key is stored in the variable named POLARIS_API_KEY. For information on how to obtain an API key and assign permissions, see Authenticate with API keys. For information on permissions, visit Permissions reference.

  • A data source in Polaris containing a day's earthquake summary data from US Geological Survey. You can view the most recent day's summary data as a newline-delimited JSON file here. Download the data and name the file sample-day-geo.json.

    You can use the Files v1 API to upload the file to Polaris.
    See About the data for more information about the sample data.

About the data​

This guide uses US Geological Survey GeoJSON summary format earthquake data.

The data contains details of seismic activity including the place where the activity occurred, geographical coordinates, the type of activity, and details including depth, intensity, and alert status.

See GeoJSON Summary Format for a full description of the data.

This guide uses Polaris APIs to answer the following questions about the data:

  • How many seismic events occurred on the sample day?
  • What was the maximum depth of the activity?
  • What was the average intensity of the activity?
  • What type of events occurred, and where?
  • What's the review status of the events?

The guide also creates the following Polaris actions from the data:

  • Provide a link for users outside Polaris to visualize the data.
  • Send an hourly warning if there are 10 or more events with a recorded intensity.
  • Send a daily report of activity with a recorded intensity—showing place, intensity, and depth.

Tip for creating API requests​

This guide contains examples of how to use the Polaris APIs to ingest and analyze the data through the use of Polaris assets—data cubes, dashboards, embedding links, alerts, and reports.

The JSON in the requests can be complex. To make things easier, you can create Polaris assets in the UI, then send a GET request to the API to retrieve the JSON and adapt it if necessary. For example:

  1. Create a data cube in the Polaris UI.
  2. Locate your data cube id: you can see it in the address bar when viewing the data cube in the UI, or send a GET request to /v1/projects/PROJECT_ID/data-cubes to list all data cubes.
  3. Send a GET request to /v1/projects/PROJECT_ID/data-cubes/DATACUBE_ID to retrieve the JSON that defines the data cube.
  4. Use the API documentation to modify the JSON as needed.
  5. Send a POST request to /v1/projects/PROJECT_ID/data-cubes with your JSON in the request body to create a new data cube.

Ingest sample data​

Launch a batch ingestion job to import data from your uploaded sample data file to a new table in Polaris. Submit a POST request to the Jobs v1 API and pass the job specification as a payload to the request.

The batch ingestion job:

  • automatically creates a table
  • specifies the file source
  • maps the source columns to the Polaris table columns

See Ingestion shortcuts for more information about these processes.

Sample request​

The following example shows how to load data from the sample-day-geo.json file into the sample-day-geo table.

The data contains nested columns so the job specification must transform the data to extract the nested values. This example uses the JSON_VALUE and JSON_QUERY functions to extract nested elements from the properties and geometry columns.

See the Jobs v1 API documentation for a description of all API properties.

Show sample request
curl --location --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/jobs" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
    "type": "batch",
    "target": {
        "type": "table",
        "tableName": "sample-day-geo"
    },
    "createTableIfNotExists": true,
    "source": {
       "fileList": [
        "sample-day-geo.json"
       ],
       "formatSettings": {
        "flattenSpec": {},
        "format": "nd-json"
      },
      "inputSchema": [
        {
          "dataType": "string",
          "name": "type"
        },
        {
          "dataType": "json",
          "name": "properties"
        },
        {
          "dataType": "json",
          "name": "geometry"
        },
        {
          "dataType": "string",
          "name": "id"
        }
      ],
      "type": "uploaded"
    },
    "mappings": [
      {
        "columnName": "__time",
        "expression": "CURRENT_TIMESTAMP"
      },
      {
        "columnName": "type",
        "expression": "\"type\""
      },
      {
        "columnName": "properties",
        "expression": "\"properties\""
      },
      {
        "columnName": "geometry",
        "expression": "\"geometry\""
      },
      {
        "columnName": "id",
        "expression": "\"id\""
      },
      {
        "columnName": "Geometry type",
        "expression": "JSON_VALUE(\"geometry\", '$.type')"
      },
      {
        "columnName": "Longitude",
        "expression": "JSON_QUERY(\"geometry\", '$.coordinates[0]')"
      },
      {
        "columnName": "Latitude",
        "expression": "JSON_QUERY(\"geometry\", '$.coordinates[1]')"
      },
      {
        "columnName": "Depth",
        "expression": "JSON_QUERY(\"geometry\", '$.coordinates[2]')"
      },
      {
        "columnName": "URL",
        "expression": "JSON_VALUE(\"properties\", '$.url')"
      },
      {
        "columnName": "Place",
        "expression": "JSON_VALUE(\"properties\", '$.place')"
      },
      {
        "columnName": "Mag type",
        "expression": "JSON_VALUE(\"properties\", '$.magType')"
      },
      {
        "columnName": "Event type",
        "expression": "JSON_VALUE(\"properties\", '$.type')"
      },
      {
        "columnName": "Review status",
        "expression": "JSON_VALUE(\"properties\", '$.status')"
      },
      {
        "columnName": "Tsunami",
        "expression": "JSON_VALUE(\"properties\", '$.tsunami')"
      },
      {
        "columnName": "Intensity",
        "expression": "JSON_VALUE(\"properties\", '$.cdi')"
      },
      {
        "columnName": "Alert level",
        "expression": "JSON_VALUE(\"properties\", '$.alert')"
      }
   ]
}'

Sample response​

The following example shows a response to a successful ingestion job.

Show sample response
{
    "source": {
        "fileList": [
            "sample-day-geo.json"
        ],
        "formatSettings": {
            "flattenSpec": {},
            "format": "nd-json"
        },
        "inputSchema": [
            {
                "dataType": "string",
                "name": "type"
            },
            {
                "dataType": "json",
                "name": "properties"
            },
            {
                "dataType": "json",
                "name": "geometry"
            },
            {
                "dataType": "string",
                "name": "id"
            }
        ],
        "type": "uploaded"
    },
    "context": {
        "mode": "nonStrict",
        "sqlQueryId": "018ee20c-0037-7b75-bc74-4af217378994",
        "maxNumTasks": 75,
        "faultTolerance": true,
        "taskAssignment": "auto",
        "maxParseExceptions": 2147483647,
        "finalizeAggregations": true,
        "durableShuffleStorage": true,
        "clusterStatisticsMergeMode": "SEQUENTIAL",
        "groupByEnableMultiValueUnnesting": false
    },
    "filterExpression": null,
    "ingestionMode": "append",
    "mappings": [
        {
            "columnName": "__time",
            "expression": "CURRENT_TIMESTAMP",
            "isAggregation": null
        },
        {
            "columnName": "type",
            "expression": "\"type\"",
            "isAggregation": null
        },
        {
            "columnName": "properties",
            "expression": "\"properties\"",
            "isAggregation": null
        },
        {
            "columnName": "geometry",
            "expression": "\"geometry\"",
            "isAggregation": null
        },
        {
            "columnName": "id",
            "expression": "\"id\"",
            "isAggregation": null
        },
        {
            "columnName": "Geometry type",
            "expression": "JSON_VALUE(\"geometry\", '$.type')",
            "isAggregation": null
        },
        {
            "columnName": "Longitude",
            "expression": "JSON_QUERY(\"geometry\", '$.coordinates[0]')",
            "isAggregation": null
        },
        {
            "columnName": "Latitude",
            "expression": "JSON_QUERY(\"geometry\", '$.coordinates[1]')",
            "isAggregation": null
        },
        {
            "columnName": "Depth",
            "expression": "JSON_QUERY(\"geometry\", '$.coordinates[2]')",
            "isAggregation": null
        },
        {
            "columnName": "URL",
            "expression": "JSON_VALUE(\"properties\", '$.url')",
            "isAggregation": null
        },
        {
            "columnName": "Place",
            "expression": "JSON_VALUE(\"properties\", '$.place')",
            "isAggregation": null
        },
        {
            "columnName": "Mag type",
            "expression": "JSON_VALUE(\"properties\", '$.magType')",
            "isAggregation": null
        },
        {
            "columnName": "Event type",
            "expression": "JSON_VALUE(\"properties\", '$.type')",
            "isAggregation": null
        },
        {
            "columnName": "Review status",
            "expression": "JSON_VALUE(\"properties\", '$.status')",
            "isAggregation": null
        },
        {
            "columnName": "Tsunami",
            "expression": "JSON_VALUE(\"properties\", '$.tsunami')",
            "isAggregation": null
        },
        {
            "columnName": "Intensity",
            "expression": "JSON_VALUE(\"properties\", '$.cdi')",
            "isAggregation": null
        },
        {
            "columnName": "Alert level",
            "expression": "JSON_VALUE(\"properties\", '$.alert')",
            "isAggregation": null
        }
    ],
    "maxParseExceptions": 2147483647,
    "query": "INSERT INTO \"sample-day-geo\"\nSELECT\n  CURRENT_TIMESTAMP AS \"__time\",\n    \"type\" AS \"type\",\n    \"properties\" AS \"properties\",\n    \"geometry\" AS \"geometry\",\n    \"id\" AS \"id\",\n    JSON_VALUE(\"geometry\", '$.type') AS \"Geometry type\",\n    JSON_QUERY(\"geometry\", '$.coordinates[0]') AS \"Longitude\",\n    JSON_QUERY(\"geometry\", '$.coordinates[1]') AS \"Latitude\",\n    JSON_QUERY(\"geometry\", '$.coordinates[2]') AS \"Depth\",\n    JSON_VALUE(\"properties\", '$.url') AS \"URL\",\n    JSON_VALUE(\"properties\", '$.place') AS \"Place\",\n    JSON_VALUE(\"properties\", '$.magType') AS \"Mag type\",\n    JSON_VALUE(\"properties\", '$.type') AS \"Event type\",\n    JSON_VALUE(\"properties\", '$.status') AS \"Review status\",\n    JSON_VALUE(\"properties\", '$.tsunami') AS \"Tsunami\",\n    JSON_VALUE(\"properties\", '$.cdi') AS \"Intensity\",\n    JSON_VALUE(\"properties\", '$.alert') AS \"Alert level\"\nFROM TABLE(\n  POLARIS_SOURCE(\n    '{\"fileList\":[\"sample-day-geo.json\"],\"formatSettings\":{\"flattenSpec\":{},\"format\":\"nd-json\"},\"inputSchema\":[{\"dataType\":\"string\",\"name\":\"type\"},{\"dataType\":\"json\",\"name\":\"properties\"},{\"dataType\":\"json\",\"name\":\"geometry\"},{\"dataType\":\"string\",\"name\":\"id\"}],\"type\":\"uploaded\"}'\n  )\n)\n\n\nPARTITIONED BY DAY",
    "createdBy": {
        "username": "api-key-pok_as0gn...fnsppw",
        "userId": "e114ec4f-e62c-420d-8cf6-97145c6e65d0"
    },
    "createdTimestamp": "2023-04-15T13:57:01.111836Z",
    "desiredExecutionStatus": "running",
    "executionStatus": "pending",
    "health": {
        "status": "ok"
    },
    "id": "018ee20c-0037-7b75-bc74-4af217378994",
    "lastModifiedBy": {
        "username": "api-key-pok_as0gn...fnsppw",
        "userId": "e114ec4f-e62c-420d-8cf6-97145c6e65d0"
    },
    "lastUpdatedTimestamp": "2023-04-15T13:57:01.111836Z",
    "spec": {
        "source": {
            "fileList": [
                "sample-day-geo.json"
            ],
            "formatSettings": {
                "flattenSpec": {},
                "format": "nd-json"
            },
            "inputSchema": [
                {
                    "dataType": "string",
                    "name": "type"
                },
                {
                    "dataType": "json",
                    "name": "properties"
                },
                {
                    "dataType": "json",
                    "name": "geometry"
                },
                {
                    "dataType": "string",
                    "name": "id"
                }
            ],
            "type": "uploaded"
        },
        "target": {
            "tableName": "sample-day-geo",
            "type": "table",
            "intervals": []
        },
        "context": {
            "mode": "nonStrict",
            "sqlQueryId": "018ee20c-0037-7b75-bc74-4af217378994",
            "maxNumTasks": 75,
            "faultTolerance": true,
            "taskAssignment": "auto",
            "maxParseExceptions": 2147483647,
            "finalizeAggregations": true,
            "durableShuffleStorage": true,
            "clusterStatisticsMergeMode": "SEQUENTIAL",
            "groupByEnableMultiValueUnnesting": false
        },
        "createTableIfNotExists": true,
        "filterExpression": null,
        "ingestionMode": "append",
        "mappings": [
            {
                "columnName": "__time",
                "expression": "CURRENT_TIMESTAMP",
                "isAggregation": null
            },
            {
                "columnName": "type",
                "expression": "\"type\"",
                "isAggregation": null
            },
            {
                "columnName": "properties",
                "expression": "\"properties\"",
                "isAggregation": null
            },
            {
                "columnName": "geometry",
                "expression": "\"geometry\"",
                "isAggregation": null
            },
            {
                "columnName": "id",
                "expression": "\"id\"",
                "isAggregation": null
            },
            {
                "columnName": "Geometry type",
                "expression": "JSON_VALUE(\"geometry\", '$.type')",
                "isAggregation": null
            },
            {
                "columnName": "Longitude",
                "expression": "JSON_QUERY(\"geometry\", '$.coordinates[0]')",
                "isAggregation": null
            },
            {
                "columnName": "Latitude",
                "expression": "JSON_QUERY(\"geometry\", '$.coordinates[1]')",
                "isAggregation": null
            },
            {
                "columnName": "Depth",
                "expression": "JSON_QUERY(\"geometry\", '$.coordinates[2]')",
                "isAggregation": null
            },
            {
                "columnName": "URL",
                "expression": "JSON_VALUE(\"properties\", '$.url')",
                "isAggregation": null
            },
            {
                "columnName": "Place",
                "expression": "JSON_VALUE(\"properties\", '$.place')",
                "isAggregation": null
            },
            {
                "columnName": "Mag type",
                "expression": "JSON_VALUE(\"properties\", '$.magType')",
                "isAggregation": null
            },
            {
                "columnName": "Event type",
                "expression": "JSON_VALUE(\"properties\", '$.type')",
                "isAggregation": null
            },
            {
                "columnName": "Review status",
                "expression": "JSON_VALUE(\"properties\", '$.status')",
                "isAggregation": null
            },
            {
                "columnName": "Tsunami",
                "expression": "JSON_VALUE(\"properties\", '$.tsunami')",
                "isAggregation": null
            },
            {
                "columnName": "Intensity",
                "expression": "JSON_VALUE(\"properties\", '$.cdi')",
                "isAggregation": null
            },
            {
                "columnName": "Alert level",
                "expression": "JSON_VALUE(\"properties\", '$.alert')",
                "isAggregation": null
            }
        ],
        "maxParseExceptions": 2147483647,
        "type": "batch",
        "desiredExecutionStatus": "running"
    },
    "target": {
        "tableName": "sample-day-geo",
        "type": "table",
        "intervals": []
    },
    "type": "batch",
    "completedTimestamp": null,
    "startedTimestamp": null
}

View the data​

To view the ingested data in the sample-day-geo table, send a POST request to the Query API.

Sample request​

Show sample request
curl --location --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/query/sql" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
  "query": "SELECT id, type, Depth, Place, \"Event type\" FROM \"sample-day-geo\" LIMIT 5"
  }'

Sample data​

The following example shows the sample data in the response. Your data will vary based on the date you downloaded the summary data.

View the data
idEvent typeDepthPlace
ci40677944earthquake9.4517 km SSW of Oasis, CA
uu80050816earthquake2.7415 km NE of Milford, Utah
nc74009011earthquake0.956 km W of Cobb, CA
uw61985591explosion-0.519 km S of Princeton, Canada
nc74008976quarry blast-0.293 km SW of Clayton, CA

Create a data cube​

A data cube is a data model that allows you to organize and visualize your data. You create a data cube from one or more source tables. Dimensions correspond to columns in the source table. Measures are numeric values derived from the table data.

Submit a POST request to the Data cubes v1 API and pass the data cube specification as a payload to the request.

Sample request​

The following example creates a data cube named Earthquake sample day from the table named sample-day-geo created in the Ingest data cube section above.

The request body contains the following properties:

  • dimensions defines dimensions for most columns in the underlying table, including Latitude and Longitude—these will be useful in the Create a dashboard section.
  • attributes defines a time filter.
  • measures defines measures for Number of events, Max depth, and Average intensity.
  • readAccess enables read access for all users in the project.
  • modifyAccess enables edit access for a single defined user.
  • downloadAccess enables downloads for a group and an additional user.

See the Data cubes v1 API documentation for a description of all API properties.

Show sample request
curl --location --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/data-cubes" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
    "title": "Earthquake sample day",
    "queryMode": "sql",
    "source": {
        "value": "sample-day-geo",
        "connectionName": "druid",
        "type": "direct"
    },
    "readAccess": {
        "access": "all"
    },
    "modifyAccess": {
        "access": "single",
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "downloadAccess": {
        "access": "specific",
        "roles": [
            "77f7787f-0249-49fa-9ce8-39c8deb4617f"
        ],
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "attributes": [
        {
            "name": "__time",
            "type": "TIME",
            "nativeType": "__time",
            "range": {
                "start": "2023-02-27T15:24:37.271Z",
                "end": "2023-02-28T15:24:37.271Z",
                "bounds": "[]"
            }
        }
    ],
    "dimensions": [
        {
            "title": "Time",
            "formula": "t.\"__time\"",
            "type": "TIME",
            "id": "__time"
        },
        {
            "title": "Alert Level",
            "formula": "t.\"Alert level\"",
            "type": "STRING",
            "id": "Alert_level"
        },
        {
            "title": "Depth",
            "formula": "t.\"Depth\"",
            "type": "NUMBER",
            "id": "Depth"
        },
        {
            "title": "Event Type",
            "formula": "t.\"Event type\"",
            "type": "STRING",
            "id": "Event_type"
        },
        {
            "title": "Coordinates",
            "group": "Geometry",
            "formula": "JSON_VALUE(t.geometry,$.coordinates)",
            "type": "STRING",
            "id": "Coordinates"
        },
        {
            "title": "Type D8d3",
            "group": "Geometry",
            "formula": "JSON_VALUE(t.geometry,$.type)",
            "type": "STRING",
            "id": "Type-d8d3"
        },
        {
            "title": "Geometry Type",
            "formula": "t.\"Geometry type\"",
            "type": "STRING",
            "id": "Geometry_type"
        },
        {
            "title": "Id",
            "formula": "t.\"id\"",
            "type": "STRING",
            "id": "id"
        },
        {
            "title": "Intensity",
            "formula": "t.\"Intensity\"",
            "type": "STRING",
            "id": "Intensity"
        },
        {
            "title": "Latitude",
            "formula": "t.\"Latitude\"",
            "type": "NUMBER",
            "geo": true,
            "geoEncoding": "lat-coordinate",
            "id": "Latitude"
        },
        {
            "title": "Longitude",
            "formula": "t.\"Longitude\"",
            "type": "NUMBER",
            "geo": true,
            "geoEncoding": "lng-coordinate",
            "id": "Longitude"
        },
        {
            "title": "Mag Type",
            "formula": "t.\"Mag type\"",
            "type": "STRING",
            "id": "Mag_type"
        },
        {
            "title": "Place",
            "formula": "t.\"Place\"",
            "type": "STRING",
            "id": "Place"
        },
        {
            "title": "Alert",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.alert)",
            "type": "STRING",
            "id": "Alert"
        },
        {
            "title": "Cdi",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.cdi)",
            "type": "STRING",
            "id": "Cdi"
        },
        {
            "title": "Code",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.code)",
            "type": "STRING",
            "id": "Code"
        },
        {
            "title": "Detail",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.detail)",
            "type": "STRING",
            "id": "Detail"
        },
        {
            "title": "Dmin",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.dmin)",
            "type": "STRING",
            "id": "Dmin"
        },
        {
            "title": "Felt",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.felt)",
            "type": "STRING",
            "id": "Felt"
        },
        {
            "title": "Gap",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.gap)",
            "type": "STRING",
            "id": "Gap"
        },
        {
            "title": "Ids",
            "group": "Properties",
            "formula": "JSON_VALUE(\t.properties,$.ids)",
            "type": "STRING",
            "id": "Ids"
        },
        {
            "title": "Mag",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.mag)",
            "type": "STRING",
            "id": "Mag"
        },
        {
            "title": "Mag Type",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.magType)",
            "type": "STRING",
            "id": "Mag_Type"
        },
        {
            "title": "Mmi",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.mmi)",
            "type": "STRING",
            "id": "Mmi"
        },
        {
            "title": "Net",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.net)",
            "type": "STRING",
            "id": "Net"
        },
        {
            "title": "Nst",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.nst)",
            "type": "STRING",
            "id": "Nst"
        },
        {
            "title": "Place 8f23",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.place)",
            "type": "STRING",
            "id": "Place-8f23"
        },
        {
            "title": "Rms",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.rms)",
            "type": "STRING",
            "id": "Rms"
        },
        {
            "title": "Sig",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.sig)",
            "type": "STRING",
            "id": "Sig"
        },
        {
            "title": "Sources",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.sources)",
            "type": "STRING",
            "id": "Sources"
        },
        {
            "title": "Status",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.status)",
            "type": "STRING",
            "id": "Status"
        },
        {
            "title": "Time",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.time)",
            "type": "STRING",
            "id": "Time"
        },
        {
            "title": "Title",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.title)",
            "type": "STRING",
            "id": "Title"
        },
        {
            "title": "Tsunami 3ce2",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.tsunami)",
            "type": "STRING",
            "id": "Tsunami-3ce2"
        },
        {
            "title": "Type",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.type)",
            "type": "STRING",
            "id": "Type"
        },
        {
            "title": "Types",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.types)",
            "type": "STRING",
            "id": "Types"
        },
        {
            "title": "Tz",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.tz)",
            "type": "STRING",
            "id": "Tz"
        },
        {
            "title": "Updated",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.updated)",
            "type": "STRING",
            "id": "Updated"
        },
        {
            "title": "Url",
            "group": "Properties",
            "formula": "JSON_VALUE(\t.properties,$.url)",
            "type": "STRING",
            "id": "Url"
        },
        {
            "title": "Review Status",
            "formula": "t.\"Review status\"",
            "type": "STRING",
            "id": "Review_status"
        },
        {
            "title": "Tsunami",
            "formula": "t.\"Tsunami\"",
            "type": "STRING",
            "id": "Tsunami"
        },
        {
            "title": "Type",
            "formula": "t.\"type\"",
            "type": "STRING",
            "id": "type"
        },
        {
            "title": "URL",
            "formula": "t.\"URL\"",
            "type": "STRING",
            "id": "URL"
        }
    ],
    "measures": [
        {
            "title": "Number of Events",
            "formula": "COUNT(*)",
            "numberStyle": {
                "type": "si",
                "leading": 1,
                "minDecimals": 2,
                "maxDecimals": 2,
                "integer": true,
                "abbreviationSpace": true
            },
            "id": "count"
        },
        {
            "title": "Max depth",
            "formula": "MAX(t.\"Depth\")",
            "id": "sum_Depth"
        },
        {
            "title": "Average intensity",
            "formula": "AVG(t.\"Intensity\")",
            "id": "AVGtInt-a71"
        }
    ],
    "specialTimeDimension": "__time",
    "enforceTimeFilter": true,
    "defaultRefreshRate": "PT5M"
}'

Sample response​

The following example shows a response to successful data cube creation.

Make a note of the datacube id in the request response. You'll need it to create the dashboard, alert, and report in later steps.

Show sample response
{
    "createdAt": "2023-04-15T13:27:36.532Z",
    "createdBy": "e114ec4f-e62c-420d-8cf6-97145c6e65d0",
    "updatedAt": "2023-04-15T13:27:36.532Z",
    "updatedBy": "e114ec4f-e62c-420d-8cf6-97145c6e65d0",
    "title": "Earthquake sample day Jill",
    "queryMode": "sql",
    "source": {
        "value": "sample-day-geo",
        "connectionName": "druid",
        "type": "direct"
    },
    "readAccess": {
        "access": "all"
    },
    "modifyAccess": {
        "access": "single",
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "downloadAccess": {
        "access": "specific",
        "roles": [
            "77f7787f-0249-49fa-9ce8-39c8deb4617f"
        ],
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "attributes": [
        {
            "name": "__time",
            "type": "TIME",
            "nativeType": "__time",
            "range": {
                "start": "2023-02-27T15:24:37.271Z",
                "end": "2023-02-28T15:24:37.271Z",
                "bounds": "[]"
            }
        }
    ],
    "dimensions": [
        {
            "title": "Time",
            "formula": "t.\"__time\"",
            "type": "TIME",
            "id": "__time"
        },
        {
            "title": "Alert Level",
            "formula": "t.\"Alert level\"",
            "type": "STRING",
            "id": "Alert_level"
        },
        {
            "title": "Depth",
            "formula": "t.\"Depth\"",
            "type": "NUMBER",
            "id": "Depth"
        },
        {
            "title": "Event Type",
            "formula": "t.\"Event type\"",
            "type": "STRING",
            "id": "Event_type"
        },
        {
            "title": "Coordinates",
            "group": "Geometry",
            "formula": "JSON_VALUE(t.geometry,$.coordinates)",
            "type": "STRING",
            "id": "Coordinates"
        },
        {
            "title": "Type D8d3",
            "group": "Geometry",
            "formula": "JSON_VALUE(t.geometry,$.type)",
            "type": "STRING",
            "id": "Type-d8d3"
        },
        {
            "title": "Geometry Type",
            "formula": "t.\"Geometry type\"",
            "type": "STRING",
            "id": "Geometry_type"
        },
        {
            "title": "Id",
            "formula": "t.\"id\"",
            "type": "STRING",
            "id": "id"
        },
        {
            "title": "Intensity",
            "formula": "t.\"Intensity\"",
            "type": "STRING",
            "id": "Intensity"
        },
        {
            "title": "Latitude",
            "formula": "t.\"Latitude\"",
            "type": "NUMBER",
            "geo": true,
            "geoEncoding": "lat-coordinate",
            "id": "Latitude"
        },
        {
            "title": "Longitude",
            "formula": "t.\"Longitude\"",
            "type": "NUMBER",
            "geo": true,
            "geoEncoding": "lng-coordinate",
            "id": "Longitude"
        },
        {
            "title": "Mag Type",
            "formula": "t.\"Mag type\"",
            "type": "STRING",
            "id": "Mag_type"
        },
        {
            "title": "Place",
            "formula": "t.\"Place\"",
            "type": "STRING",
            "id": "Place"
        },
        {
            "title": "Alert",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.alert)",
            "type": "STRING",
            "id": "Alert"
        },
        {
            "title": "Cdi",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.cdi)",
            "type": "STRING",
            "id": "Cdi"
        },
        {
            "title": "Code",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.code)",
            "type": "STRING",
            "id": "Code"
        },
        {
            "title": "Detail",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.detail)",
            "type": "STRING",
            "id": "Detail"
        },
        {
            "title": "Dmin",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.dmin)",
            "type": "STRING",
            "id": "Dmin"
        },
        {
            "title": "Felt",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.felt)",
            "type": "STRING",
            "id": "Felt"
        },
        {
            "title": "Gap",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,'$.gap)",
            "type": "STRING",
            "id": "Gap"
        },
        {
            "title": "Ids",
            "group": "Properties",
            "formula": "JSON_VALUE(\t.properties,$.ids)",
            "type": "STRING",
            "id": "Ids"
        },
        {
            "title": "Mag",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.mag)",
            "type": "STRING",
            "id": "Mag"
        },
        {
            "title": "Mag Type",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.magType)",
            "type": "STRING",
            "id": "Mag_Type"
        },
        {
            "title": "Mmi",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.mmi)",
            "type": "STRING",
            "id": "Mmi"
        },
        {
            "title": "Net",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.net)",
            "type": "STRING",
            "id": "Net"
        },
        {
            "title": "Nst",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.nst)",
            "type": "STRING",
            "id": "Nst"
        },
        {
            "title": "Place 8f23",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.place)",
            "type": "STRING",
            "id": "Place-8f23"
        },
        {
            "title": "Rms",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.rms)",
            "type": "STRING",
            "id": "Rms"
        },
        {
            "title": "Sig",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.sig)",
            "type": "STRING",
            "id": "Sig"
        },
        {
            "title": "Sources",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.sources)",
            "type": "STRING",
            "id": "Sources"
        },
        {
            "title": "Status",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.status)",
            "type": "STRING",
            "id": "Status"
        },
        {
            "title": "Time",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.time)",
            "type": "STRING",
            "id": "Time"
        },
        {
            "title": "Title",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.title)",
            "type": "STRING",
            "id": "Title"
        },
        {
            "title": "Tsunami 3ce2",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.tsunami)",
            "type": "STRING",
            "id": "Tsunami-3ce2"
        },
        {
            "title": "Type",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.type)",
            "type": "STRING",
            "id": "Type"
        },
        {
            "title": "Types",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.types)",
            "type": "STRING",
            "id": "Types"
        },
        {
            "title": "Tz",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.tz)",
            "type": "STRING",
            "id": "Tz"
        },
        {
            "title": "Updated",
            "group": "Properties",
            "formula": "JSON_VALUE(t.properties,$.updated)",
            "type": "STRING",
            "id": "Updated"
        },
        {
            "title": "Url",
            "group": "Properties",
            "formula": "JSON_VALUE(\t.properties,$.url)",
            "type": "STRING",
            "id": "Url"
        },
        {
            "title": "Review Status",
            "formula": "t.\"Review status\"",
            "type": "STRING",
            "id": "Review_status"
        },
        {
            "title": "Tsunami",
            "formula": "t.\"Tsunami\"",
            "type": "STRING",
            "id": "Tsunami"
        },
        {
            "title": "Type",
            "formula": "t.\"type\"",
            "type": "STRING",
            "id": "type"
        },
        {
            "title": "URL",
            "formula": "t.\"URL\"",
            "type": "STRING",
            "id": "URL"
        }
    ],
    "measures": [
        {
            "title": "Number of Events",
            "formula": "COUNT(*)",
            "numberStyle": {
                "type": "si",
                "leading": 1,
                "minDecimals": 2,
                "maxDecimals": 2,
                "integer": true,
                "abbreviationSpace": true
            },
            "id": "count"
        },
        {
            "title": "Max depth",
            "formula": "MAX(t.\"Depth\")",
            "id": "sum_Depth"
        },
        {
            "title": "Average intensity",
            "formula": "AVG(t.\"Intensity\")",
            "id": "AVGtInt-a71"
        }
    ],
    "specialTimeDimension": "__time",
    "enforceTimeFilter": true,
    "defaultRefreshRate": "PT5M",
    "id": "sample-day-geo1c2d"
}

Data cube display​

The following screenshot shows this data cube in the Polaris UI:

Polaris data cube

Create a dashboard​

A dashboard contains visualizations of the data in one or more data cubes. Dashboards contain at least one tile on at least one page. You can use a dashboard to explore and draw insights from your data.

Submit a POST request to the Dashboards v1 API and pass the dashboard, page, and tile specifications as a payload to the request.

Sample request​

The following example creates a dashboard named 1 day quake data from the data cube with id sample-day-geo1c2d created in the Create a data cube section. Replace the data cube ID with your own if you copy the request.

The request body contains the following properties:

  • pages defines a single dashboard page.
  • tiles configures 4 dashboard tiles:
    • street-map defines a visualization named Longitude, Latitude by Number of Events, showing Latitude and Longitude dimensions with start and end values.
    • table defines a visualization named Intensity by Place, showing the number of events with each intensity by place.
    • vertical-bars defines a visualization named Depth & event type, showing the depth for each type of seismic activity.
    • pie-chart defines a visualization named Review status, showing the number of events by review status.
  • readAccess enables read access for all users in the project.
  • modifyAccess enables edit access for a role and an additional user.

See the Dashboards v1 API documentation for a description of all API properties.

Show sample request
curl --location --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/dashboards" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
  "title": "1 day quake data",
  "type": "dashboard2",
  "readAccess": {
    "access": "all"
  },
  "modifyAccess": {
    "access": "specific",
    "roles": [
      "77f7787f-0249-49fa-9ce8-39c8deb4617f"
    ],
    "users": [
      "bde8897b-38e0-412f-b008-267596f0b2ef"
    ]
  },
  "pages": [
    {
      "label": "New page",
      "tiles": [
        {
          "type": "visualization",
          "title": "Longitude, Latitude by Number of Events",
          "canExpand": true,
          "description": "",
          "position": {
            "width": 10,
            "height": 6
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {
              "clauses": [
                {
                  "dimension": "__time",
                  "action": "overlap",
                  "dynamic": {
                    "op": "timeRange",
                    "operand": {
                      "op": "ref",
                      "name": "m"
                    },
                    "duration": "P1D",
                    "step": -1,
                    "bounds": "[)"
                  }
                },
                {
                  "dimension": "Longitude",
                  "action": "overlap",
                  "values": {
                    "setType": "NUMBER_RANGE",
                    "elements": [
                      {
                        "start": -127.56433282702334,
                        "end": -84.39534865732624
                      }
                    ]
                  },
                  "internal": true
                },
                {
                  "dimension": "Latitude",
                  "action": "overlap",
                  "values": {
                    "setType": "NUMBER_RANGE",
                    "elements": [
                      {
                        "start": 8.289316552888451,
                        "end": 48.284284955960345
                      }
                    ]
                  },
                  "internal": true
                }
              ]
            },
            "axesSplits": [
              [
                {
                  "dimension": "Longitude",
                  "bucketAction": {
                    "op": "numberBucket",
                    "size": 0.6166998
                  },
                  "sortType": "dimension",
                  "direction": "ascending",
                  "limit": 1000
                }
              ],
              [
                {
                  "dimension": "Latitude",
                  "bucketAction": {
                    "op": "numberBucket",
                    "size": 0.5713567
                  },
                  "sortType": "dimension",
                  "direction": "ascending",
                  "limit": 1000
                }
              ]
            ],
            "visualization": "street-map",
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "e00055ba-765e-4f12-89fe-0bfe9aeeab71"
              }
            ],
            "pinnedDimensions": []
          },
          "id": "t01"
        },
        {
          "type": "visualization",
          "title": "Intensity by Place",
          "titleHidden": true,
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 9,
            "height": 3,
            "x": 10,
            "y": 3
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {
              "clauses": [
                {
                  "dimension": "__time",
                  "action": "overlap",
                  "dynamic": {
                    "op": "timeRange",
                    "operand": {
                      "op": "ref",
                      "name": "m"
                    },
                    "duration": "P1D",
                    "step": -1,
                    "bounds": "[)"
                  }
                },
                {
                  "dimension": "Intensity",
                  "action": "overlap",
                  "values": {
                    "setType": "NULL",
                    "elements": [
                      null
                    ]
                  },
                  "exclude": true,
                  "mvFilterOnly": false
                }
              ]
            },
            "axesSplits": [
              [
                {
                  "dimension": "Intensity",
                  "sortType": "measure",
                  "direction": "descending"
                },
                {
                  "dimension": "Place",
                  "sortType": "measure",
                  "direction": "descending"
                }
              ],
              []
            ],
            "visualization": "table",
            "visualizationOptions": {
              "rowLayout": "nested"
            },
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "694fba9b-e119-42e1-9acd-4984a6eada95"
              }
            ],
            "pinnedDimensions": []
          },
          "id": "tb433"
        },
        {
          "type": "visualization",
          "title": "Depth & event type",
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 5,
            "height": 3,
            "x": 10
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {
              "clauses": [
                {
                  "dimension": "__time",
                  "action": "overlap",
                  "dynamic": {
                    "op": "timeRange",
                    "operand": {
                      "op": "ref",
                      "name": "m"
                    },
                    "duration": "P1D",
                    "step": -1,
                    "timezone": "Etc/UTC"
                  },
                  "exclude": false
                }
              ]
            },
            "axesSplits": [
              [
                {
                  "dimension": "Depth",
                  "sortType": "dimension",
                  "direction": "ascending"
                }
              ],
              [
                {
                  "dimension": "Event_type",
                  "sortType": "measure",
                  "direction": "descending"
                }
              ],
              []
            ],
            "visualization": "vertical-bars",
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "3c1d7dc2-aad4-48a8-929a-6713508e4cd5"
              }
            ],
            "pinnedDimensions": []
          },
          "legendSide": "bottom",
          "id": "7756"
        },
        {
          "type": "visualization",
          "title": "Review status",
          "titleHidden": false,
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 4,
            "height": 2,
            "x": 15
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {},
            "axesSplits": [
              [
                {
                  "dimension": "Review_status",
                  "sortType": "measure",
                  "direction": "descending"
                }
              ]
            ],
            "visualization": "pie-chart",
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "fd1376b8-d80c-4a70-9230-a529fba2e017"
              }
            ],
            "pinnedDimensions": []
          },
          "legendSide": "none",
          "id": "f1a0"
        },
        {
          "type": "visualization",
          "title": "Events over time",
          "titleHidden": true,
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 4,
            "height": 1,
            "x": 15,
            "y": 2
          },
          "exploreEssence": {
            "parameters": {
              "singleMetricTitle": "",
              "metrics": [
                {
                  "expression": "MEASURE_BY_NAME(AVGtInt-a71)",
                  "name": "Average intensity",
                  "sqlType": "DOUBLE",
                  "multiValue": false,
                  "format": "{\"type\":\"si\",\"leading\":1,\"minDecimals\":2,\"maxDecimals\":2,\"abbreviationSpace\":true}",
                  "id": "AVGtInt-a71"
                }
              ],
              "timeSplit": {
                "expression": "\"DIM:__time\"",
                "name": "Time",
                "sqlType": "TIMESTAMP",
                "multiValue": false,
                "id": "__time",
                "granularity": "PT1M"
              },
              "conditionalFormatting": [
                {
                  "type": "largerThan",
                  "leftValue": 100,
                  "intent": "WARNING"
                }
              ]
            },
            "dataCube": "sample-day-geo1c2d",
            "moduleName": "overall",
            "where": "(TIME_SHIFT(MAX_DATA_TIME(), 'P1D', -1, 'Etc/UTC') <= \"DIM:__time\" AND \"DIM:__time\" < MAX_DATA_TIME())",
            "transferGroups": {},
            "timezone": "Etc/UTC"
          },
          "id": "te3fd"
        }
      ],
      "id": "page"
    }
  ]
}'

Sample response​

The following example shows a response to successful dashboard creation.

Make a note of the dashboard id in the request response. You'll need it to create the embedding link in a later step.

Show sample response
{
  "createdAt": "2023-04-15T14:29:36.119Z",
  "createdBy": "e114ec4f-e62c-420d-8cf6-97145c6e65d0",
  "updatedAt": "2023-04-15T14:29:36.119Z",
  "updatedBy": "e114ec4f-e62c-420d-8cf6-97145c6e65d0",
  "title": "1 day quake data Jill again",
  "type": "dashboard2",
  "readAccess": {
    "access": "all"
  },
  "modifyAccess": {
    "access": "specific",
    "roles": [
      "77f7787f-0249-49fa-9ce8-39c8deb4617f"
    ],
    "users": [
      "bde8897b-38e0-412f-b008-267596f0b2ef"
    ]
  },
  "pages": [
    {
      "label": "New page",
      "tiles": [
        {
          "type": "visualization",
          "title": "Longitude, Latitude by Number of Events",
          "canExpand": true,
          "description": "",
          "position": {
            "width": 10,
            "height": 6
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {
              "clauses": [
                {
                  "dimension": "__time",
                  "action": "overlap",
                  "dynamic": {
                    "op": "timeRange",
                    "operand": {
                      "op": "ref",
                      "name": "m"
                    },
                    "duration": "P1D",
                    "step": -1,
                    "bounds": "[)"
                  }
                },
                {
                  "dimension": "Longitude",
                  "action": "overlap",
                  "values": {
                    "setType": "NUMBER_RANGE",
                    "elements": [
                      {
                        "start": -127.56433282702334,
                        "end": -84.39534865732624
                      }
                    ]
                  },
                  "internal": true
                },
                {
                  "dimension": "Latitude",
                  "action": "overlap",
                  "values": {
                    "setType": "NUMBER_RANGE",
                    "elements": [
                      {
                        "start": 8.289316552888451,
                        "end": 48.284284955960345
                      }
                    ]
                  },
                  "internal": true
                }
              ]
            },
            "axesSplits": [
              [
                {
                  "dimension": "Longitude",
                  "bucketAction": {
                    "op": "numberBucket",
                    "size": 0.6166998
                  },
                  "sortType": "dimension",
                  "direction": "ascending",
                  "limit": 1000
                }
              ],
              [
                {
                  "dimension": "Latitude",
                  "bucketAction": {
                    "op": "numberBucket",
                    "size": 0.5713567
                  },
                  "sortType": "dimension",
                  "direction": "ascending",
                  "limit": 1000
                }
              ]
            ],
            "visualization": "street-map",
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "e00055ba-765e-4f12-89fe-0bfe9aeeab71"
              }
            ],
            "pinnedDimensions": []
          },
          "id": "t01"
        },
        {
          "type": "visualization",
          "title": "Intensity by Place",
          "titleHidden": true,
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 9,
            "height": 3,
            "x": 10,
            "y": 3
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {
              "clauses": [
                {
                  "dimension": "__time",
                  "action": "overlap",
                  "dynamic": {
                    "op": "timeRange",
                    "operand": {
                      "op": "ref",
                      "name": "m"
                    },
                    "duration": "P1D",
                    "step": -1,
                    "bounds": "[)"
                  }
                },
                {
                  "dimension": "Intensity",
                  "action": "overlap",
                  "values": {
                    "setType": "NULL",
                    "elements": [
                      null
                    ]
                  },
                  "exclude": true,
                  "mvFilterOnly": false
                }
              ]
            },
            "axesSplits": [
              [
                {
                  "dimension": "Intensity",
                  "sortType": "measure",
                  "direction": "descending"
                },
                {
                  "dimension": "Place",
                  "sortType": "measure",
                  "direction": "descending"
                }
              ],
              []
            ],
            "visualization": "table",
            "visualizationOptions": {
              "rowLayout": "nested"
            },
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "694fba9b-e119-42e1-9acd-4984a6eada95"
              }
            ],
            "pinnedDimensions": []
          },
          "id": "tb433"
        },
        {
          "type": "visualization",
          "title": "Depth & event type",
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 5,
            "height": 3,
            "x": 10
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {
              "clauses": [
                {
                  "dimension": "__time",
                  "action": "overlap",
                  "dynamic": {
                    "op": "timeRange",
                    "operand": {
                      "op": "ref",
                      "name": "m"
                    },
                    "duration": "P1D",
                    "step": -1,
                    "timezone": "Etc/UTC"
                  },
                  "exclude": false
                }
              ]
            },
            "axesSplits": [
              [
                {
                  "dimension": "Depth",
                  "sortType": "dimension",
                  "direction": "ascending"
                }
              ],
              [
                {
                  "dimension": "Event_type",
                  "sortType": "measure",
                  "direction": "descending"
                }
              ],
              []
            ],
            "visualization": "vertical-bars",
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "3c1d7dc2-aad4-48a8-929a-6713508e4cd5"
              }
            ],
            "pinnedDimensions": []
          },
          "legendSide": "bottom",
          "id": "7756"
        },
        {
          "type": "visualization",
          "title": "Review status",
          "titleHidden": false,
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 4,
            "height": 2,
            "x": 15
          },
          "facetEssence": {
            "dataCube": "sample-day-geo1c2d",
            "timezone": "Etc/UTC",
            "filter": {},
            "axesSplits": [
              [
                {
                  "dimension": "Review_status",
                  "sortType": "measure",
                  "direction": "descending"
                }
              ]
            ],
            "visualization": "pie-chart",
            "selectedMeasures": [
              {
                "measure": "count",
                "id": "fd1376b8-d80c-4a70-9230-a529fba2e017"
              }
            ],
            "pinnedDimensions": []
          },
          "legendSide": "none",
          "id": "f1a0"
        },
        {
          "type": "visualization",
          "title": "Events over time",
          "titleHidden": true,
          "infoHidden": true,
          "canExpand": true,
          "description": "",
          "position": {
            "width": 4,
            "height": 1,
            "x": 15,
            "y": 2
          },
          "exploreEssence": {
            "parameters": {
              "singleMetricTitle": "",
              "metrics": [
                {
                  "expression": "MEASURE_BY_NAME('AVGtInt-a71')",
                  "name": "Average intensity",
                  "sqlType": "DOUBLE",
                  "multiValue": false,
                  "format": "{\"type\":\"si\",\"leading\":1,\"minDecimals\":2,\"maxDecimals\":2,\"abbreviationSpace\":true}",
                  "id": "AVGtInt-a71"
                }
              ],
              "timeSplit": {
                "expression": "\"DIM:__time\"",
                "name": "Time",
                "sqlType": "TIMESTAMP",
                "multiValue": false,
                "id": "__time",
                "granularity": "PT1M"
              },
              "conditionalFormatting": [
                {
                  "type": "largerThan",
                  "leftValue": 100,
                  "intent": "WARNING"
                }
              ]
            },
            "dataCube": "sample-day-geo1c2d",
            "moduleName": "overall",
            "where": "(TIME_SHIFT(MAX_DATA_TIME(), 'P1D', -1, 'Etc/UTC') <= \"DIM:__time\" AND \"DIM:__time\" < MAX_DATA_TIME())",
            "transferGroups": {},
            "timezone": "Etc/UTC"
          },
          "id": "te3fd"
        }
      ],
      "id": "page"
    }
  ],
  "id": "7dfe"
}

Dashboard display​

The following screenshot shows this dashboard in the Polaris UI:

Polaris dashboard

An embedding link provides users outside Polaris with a way to view visualizations outside the Polaris UI. A link to a visualization can be public or restricted. You can share links or embed them in third-party apps.

Submit a POST request to the Embedding links v1 API and pass the visualization configuration as a payload to the request.

Sample request​

The following example creates a restricted embedding link to the dashboard with ID 7dfe created in the Create a dashboard section. Replace the dashboard ID with your own if you copy the request.

The request body contains the following properties:

  • layout hides the dashboard's navigation panel and header bar.
  • restricted creates a restricted link and generates a secret key in the response.
  • nonFilterableDimensions prevents users from changing the Latitude and Longitude settings on the map.
  • nonShowableDimensions excludes Url from the show bar of the embedded dashboard.

See the Embedding links v1 API documemtation for a description of all API properties.

info

Use the verbose option -v to include the header information in the response. Polaris returns the embedding link in the location header.

Show sample request
curl --location -v --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/embedding-links" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
    "name": "Quake dashboard API",
    "description": "1 day quake data dashboard including map",
    "layout": "visualization-only",
    "restricted": true,
    "ttl": 3600000,
    "nonFilterableDimensions": [
        "Latitude",
        "Longitude"
    ],
    "nonShowableDimensions": [
        "Url"
    ],
    "viewDescription": {
        "dashboard": "7dfe"
    }
}'

Sample response​

The following example shows a response to successful embedding link creation. The embedding link is contained in the Location header. Note that the response includes embeddingSecret which contains a SECRET_KEY. See Restrict an embedding link for information on using the secret key to generate restricted links to a visualization.

Show sample response
> Content-Type: application/json
> Content-Length: 404
>
< HTTP/1.1 201 Created
< Access-Control-Allow-Credentials: true
< Content-Type: application/json; charset=utf-8
< Date: Wed, 16 Apr 2024 13:13:46 GMT
< ETag: W/"20e-aWHxc74IO20n+Ylj2AWPTg+C3kA"
< Location: https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/embedding-links/66151f5a68c7a3f002
< Vary: Accept-Encoding
< vary: Origin
< Content-Length: 526
< Connection: keep-alive

{
    "createdAt": "2024-04-16T13:13:46.932Z",
    "createdBy": "f35c9fe5-8ec4-4d9a-8222-c03a06fb3552",
    "updatedAt": "2024-04-16T13:13:46.932Z",
    "updatedBy": "f35c9fe5-8ec4-4d9a-8222-c03a06fb3552",
    "name": "Quake dashboard",
    "description": "1 day quake data dashboard including map",
    "layout": "visualization-only",
    "apiCreated": true,
    "restricted": true,
    "ttl": 3600000,
    "nonFilterableDimensions": [
        "Latitude",
        "Longitude"
    ],
    "nonShowableDimensions": [
        "Url"
    ],
    "viewDescription": {
        "dashboard": "7dfe"
    },
    "id": "acf22f9751be622ad1",
    "embeddingSecret": "SECRET_KEY"
}

Create an alert​

An alert monitors for when one or more conditions in a data cube match configurable conditions. You can specify alert recipients and alert methods.

Submit a POST request to the Alerts v1 API and pass the alert configuration as a payload to the request.

Sample request​

The following example creates an alert from the data cube with ID sample-day-geo1c2d created in the Create a data cube section. Replace the data cube ID with your own if you copy the request.

The request body contains the following properties:

  • checkFrequency determines that Polaris evaluates the alert criteria every hour.
  • timeFrame tells Polaris to consider data from the previous hour when evaluating the alert.
  • filter contains criteria to restrict the data Polaris gathers during alert evaluation.
  • conditions tells Polaris to trigger the alert if there are more than 10 events with an intensity not equal to zero.
  • webhooks contains a Slack webhook.
  • compare sets a comparison period for the previous hour.
  • readAccess, recipients, admins, and externalEmails define access to, and control over, the alert.

The alert triggers a warning hourly if there are 10 or more events with an intensity greater than zero.

See the Alerts v1 API documentation for a description of all API properties.

Show sample request
curl --location --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/alerts" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
   "title": "10+ events with intensity > 0",
   "dataCube": "sample-day-geo1c2d",
   "checkFrequency": "PT1H",
   "owner": "bde8897b-38e0-412f-b008-267596f0b2ef",
   "timeFrame": "PT1H",
   "filter": {
      "clauses": [
        {
          "dimension": "__time",
          "action": "overlap",
          "dynamic": {
            "op": "timeRange",
            "operand": {
              "op": "ref",
              "name": "m"
            },
            "duration": "P1D",
            "step": -1,
            "bounds": "[)"
          }
        },
        {
          "dimension": "Intensity",
          "action": "overlap",
          "values": {
            "setType": "NULL",
            "elements": [
              null
            ]
          },
          "exclude": true,
          "mvFilterOnly": false
        }
      ]
    },
    "conditions": [
      {
        "type": "value",
        "measure": "count",
        "condition": "greaterThan",
        "value": 10
      }
    ],
    "severity": "warning",
    "readAccess": {
        "access": "all"
    },
    "recipients": {
        "access": "single",
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "admins": {
        "access": "specific",
        "roles": [
            "77f7787f-0249-49fa-9ce8-39c8deb4617f"
        ],
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "externalEmails": [
        "user@example.com"
    ],
    "webhooks": [
        {
            "type": "slack",
            "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
            "payload": "{\n    \"attachments\": [\n      {\n        \"fallback\": \"%title%\",\n        \"color\": \"%color%\",\n        \"title\": \"%title%\",\n        \"title_link\": \"%link%\",\n        \"text\": \"%summary%\",\n        \"summaryData\": %summaryData%,\n        \"ts\": %triggerDate%,\n        \"footer\": \"%footer%\",\n        \"footer_icon\": \"https://my-imply.io/favicon/apple-touch-icon.png\",\n        \"checkFrequency\": \"%checkFrequency%\",\n        \"timeFrame\": \"%timeFrame%\"\n      }\n    ]\n}"
        }
    ],
    "disabled": false,
    "compare": {
      "type": "relative",
      "duration": "PT1H"
    }
}'

Sample response​

The following example shows a response to successful alert creation.

Show sample response
{
    "createdAt": "2023-03-21T13:34:42.762Z",
    "createdBy": "API",
    "updatedAt": "2023-03-21T13:34:42.762Z",
    "updatedBy": "API",
    "owner": "bde8897b-38e0-412f-b008-267596f0b2ef",
    "title": "10+ events with intensity > 0",
    "dataCube": "sample-day-geo1c2d",
    "checkFrequency": "PT1H",
    "timeFrame": "PT1H",
    "filter": {
        "clauses": [
            {
                "dimension": "__time",
                "action": "overlap",
                "dynamic": {
                    "op": "timeRange",
                    "operand": {
                        "op": "ref",
                        "name": "m"
                    },
                    "duration": "P1D",
                    "step": -1,
                    "bounds": "[)"
                }
            },
            {
                "dimension": "Intensity",
                "action": "overlap",
                "values": {
                    "setType": "NULL",
                    "elements": [
                        null
                    ]
                },
                "exclude": true,
                "mvFilterOnly": false
            }
        ]
    },
    "conditions": [
        {
            "type": "value",
            "measure": "count",
            "condition": "greaterThan",
            "value": 10
        }
    ],
    "severity": "warning",
    "readAccess": {
        "access": "all"
    },
    "recipients": {
        "access": "single",
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "admins": {
        "access": "specific",
        "roles": [
            "77f7787f-0249-49fa-9ce8-39c8deb4617f"
        ],
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "externalEmails": [
        "user@example.com"
    ],
    "webhooks": [
        {
            "type": "slack",
            "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
            "payload": "{\n    \"attachments\": [\n      {\n        \"fallback\": \"%title%\",\n        \"color\": \"%color%\",\n        \"title\": \"%title%\",\n        \"title_link\": \"%link%\",\n        \"text\": \"%summary%\",\n        \"summaryData\": %summaryData%,\n        \"ts\": %triggerDate%,\n        \"footer\": \"%footer%\",\n        \"footer_icon\": \"https://my-imply.io/favicon/apple-touch-icon.png\",\n        \"checkFrequency\": \"%checkFrequency%\",\n        \"timeFrame\": \"%timeFrame%\"\n      }\n    ]\n}"
        }
    ],
    "disabled": false,
    "compare": {
        "type": "relative",
        "duration": "PT1H"
    },
    "id": "5fa3"
}

Alert email​

The following screenshot shows an email notification for the alert:

Polaris alert

Create a report​

You can schedule a report to deliver specified data to selected recipients. You configure a report to include data cube data that meets your criteria.

Submit a POST request to the Reports v1 API and pass the report configuration as a payload to the request.

Sample request​

The following example creates a report from the data cube with ID sample-day-geo1c2d created in the Create a data cube section. Replace the data cube ID with your own if you copy the request.

The request body contains the following properties:

  • delivery tells Polaris to deliver the report daily at 3 PM.
  • timeFrame tells Polaris to include data from the previous day in the report.
  • facetEssence contains the dataCube ID and a filter with criteria to define the data Polaris displays on the report—Place, Intensity, and Depth where Intensity is not null.
  • readAccess, recipients, admins, and externalEmails define access to, and control over, the report.

See the Reports v1 API documentation for a description of all API properties.

Show sample request
curl --location -v --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/reports" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
  "owner": "bde8897b-38e0-412f-b008-267596f0b2ef",
  "title": "Activity by Place",
  "creationDate": "2023-03-21T14:05:29.036Z",
  "description": "Activity by Place with Intensity and Depth",
  "disabled": true,
  "delivery": {
    "frequency": "P1D",
    "day": 1,
    "time": 15,
    "dayType": "of-week",
    "frequencyType": "fixed"
  },
  "timeFrame": {
    "interval": "previous_day",
    "startDay": 0,
    "startTime": 15
  },
  "facetEssence": {
    "dataCube": "sample-day-geo1c2d",
    "timezone": "Etc/UTC",
    "filter": {
      "clauses": [
        {
          "dimension": "__time",
          "action": "overlap",
          "dynamic": {
            "op": "timeRange",
            "operand": {
              "op": "ref",
              "name": "m"
            },
            "duration": "P1D",
            "step": -1,
            "bounds": "[)"
          }
        },
        {
          "dimension": "Intensity",
          "action": "overlap",
          "values": {
            "setType": "NULL",
            "elements": [
              null
            ]
          },
          "exclude": true,
          "mvFilterOnly": false
        }
      ]
    },
    "axesSplits": [
      [
        {
          "dimension": "Place",
          "sortType": "measure",
          "direction": "descending"
        },
        {
          "dimension": "Intensity",
          "sortType": "measure",
          "direction": "descending"
        },
        {
          "dimension": "Depth",
          "sortType": "dimension",
          "direction": "ascending"
        }
      ],
      []
    ],
    "visualization": "table",
    "selectedMeasures": [
      {
        "measure": "count",
        "id": "74750905-0561-42c8-9c98-7015d5e94409"
      }
    ],
    "pinnedDimensions": []
  },
  "readAccess": {
    "access": "all"
  },
  "recipients": {
    "access": "single",
    "users": [
      "bde8897b-38e0-412f-b008-267596f0b2ef"
    ]
  },
  "admins": {
    "access": "specific",
    "roles": [
      "77f7787f-0249-49fa-9ce8-39c8deb4617f"
    ],
    "users": [
      "bde8897b-38e0-412f-b008-267596f0b2ef"
    ]
  },
  "externalEmails": [
    "user@example.com"
  ],
  "enforceDecimalFormatting": true,
  "addTotalRowToFile": true,
  "preferredView": "pivot2"
}'

Sample response​

The following example shows a response to successful report creation.

Show sample response
{
    "createdAt": "2023-04-16T14:17:45.217Z",
    "createdBy": "e114ec4f-e62c-420d-8cf6-97145c6e65d0",
    "updatedAt": "2023-04-16T14:17:45.217Z",
    "updatedBy": "e114ec4f-e62c-420d-8cf6-97145c6e65d0",
    "owner": "bde8897b-38e0-412f-b008-267596f0b2ef",
    "creationDate": "2023-03-21T14:05:29.036Z",
    "title": "Activity by Place Jill",
    "description": "Activity by Place with Intensity and Depth",
    "disabled": true,
    "delivery": {
        "frequency": "P1D",
        "day": 1,
        "time": 15,
        "dayType": "of-week",
        "frequencyType": "fixed"
    },
    "timeFrame": {
        "interval": "previous_day",
        "startDay": 0,
        "startTime": 15
    },
    "facetEssence": {
        "dataCube": "sample-day-geo1c2d",
        "timezone": "Etc/UTC",
        "filter": {
            "clauses": [
                {
                    "dimension": "__time",
                    "action": "overlap",
                    "dynamic": {
                        "op": "timeRange",
                        "operand": {
                            "op": "ref",
                            "name": "m"
                        },
                        "duration": "P1D",
                        "step": -1,
                        "bounds": "[)"
                    }
                },
                {
                    "dimension": "Intensity",
                    "action": "overlap",
                    "values": {
                        "setType": "NULL",
                        "elements": [
                            null
                        ]
                    },
                    "exclude": true,
                    "mvFilterOnly": false
                }
            ]
        },
        "axesSplits": [
            [
                {
                    "dimension": "Place",
                    "sortType": "measure",
                    "direction": "descending"
                },
                {
                    "dimension": "Intensity",
                    "sortType": "measure",
                    "direction": "descending"
                },
                {
                    "dimension": "Depth",
                    "sortType": "dimension",
                    "direction": "ascending"
                }
            ],
            []
        ],
        "visualization": "table",
        "selectedMeasures": [
            {
                "measure": "count",
                "id": "74750905-0561-42c8-9c98-7015d5e94409"
            }
        ],
        "pinnedDimensions": []
    },
    "readAccess": {
        "access": "all"
    },
    "recipients": {
        "access": "single",
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "admins": {
        "access": "specific",
        "roles": [
            "77f7787f-0249-49fa-9ce8-39c8deb4617f"
        ],
        "users": [
            "bde8897b-38e0-412f-b008-267596f0b2ef"
        ]
    },
    "externalEmails": [
        "user@example"
    ],
    "enforceDecimalFormatting": true,
    "addTotalRowToFile": true,
    "preferredView": "pivot2",
    "id": "4c51"
}

Report email​

The following screenshot shows an email notification for the report:

Polaris alert

Learn more​

See the following topics for information on how to manage analytics features in the Polaris UI: