Quickstart

This quickstart shows you how to use the Imply Polaris web interface to load batch file data, query, and visualize data.

For a high-level overview of Polaris components, see Key concepts.

Prerequisites

Before you use this quickstart, make sure you have:

  • A Polaris account
  • One of the supported browsers:
    • Last three versions of Chrome, Firefox, Edge (Chromium version), Opera
    • Firefox ESR
    • Safari (desktop) 14.1 or above

Sign up for an Imply Polaris account

If you don't already have a Polaris account, sign up for a limited trial:

  1. Go to https://signup.imply.io.
  2. Enter your first and last name, work email, and click Continue.

    Polaris doesn't accept free email addresses for new accounts.

  3. Enter a password and a valid organization name. Your organization name must meet the following criteria:
    • It must contain a minimum of 3 and a maximum of 63 characters. Characters are letters, numbers, and dashes.
    • It must begin with a letter or a number and end with a letter or a number.
    • It cannot start or end with a dash.
    • It cannot contain symbols such as asterisks, underscores, and exclamation points.
    • It cannot end with -imply-cloud.
  4. Accept the Terms and Conditions and click Sign up to Imply.
  5. Check your inbox for a confirmation email from Imply. You must verify your email address to create an organization in Polaris.

If you do not receive a confirmation email or have trouble signing up, please contact Polaris customer support at polaris-trial@imply.io.

Access your organization

Check your inbox for a welcome email from Imply. The email contains a link to your Polaris organization account. Click on the link in the email to access your account.

You can also access your account by going to the following URL:

https://<organization>.app.imply.io/home

Replace the <organization> placeholder with the name of your organization.

Note that if you try to log in immediately after you sign up, you might have to wait a few minutes for your account to be created.

Log in

When you log in, Polaris displays your home page:

Polaris landing page

See Navigate the console to learn about the features of the Polaris UI.

Load data

This tutorial guides you through the steps to load batch data into a table so you can start using Polaris quickly. To learn more about table design, see Create a schema.

Create a table and start an ingestion job

To create a table, follow these steps:

  1. Download a day of clickstream activity from KoalasToTheMax.com. You'll use this newline delimited JSON file as the source data for the quickstart. See Supported data formats for more information on data and file format support in Polaris.
  2. In the Polaris UI, click Create a table and load data on the home screen.
  3. Give your table a meaningful name. For this example we'll use "Koalas to the Max" for the table name. Table names must be unique. Once you create a table, you can't change its name.
  4. When you're ready, click Continue.
  5. Polaris gives you the option to manually define a schema or upload a file. For the purposes of the quickstart, click Start Batch Ingestion. See Create a schema to learn about defining a schema manually.
  6. Click Select files from your computer and choose the file you downloaded, kttm-2019-08-19.json.gz. For this tutorial, you only choose the one file. However, you can choose multiple files for a single ingestion job. Note that file names must be unique.
  7. When the upload is complete, click Continue.

View and configure your table schema

Polaris samples your data and uses the data to suggest a schema based upon your source data. It displays the column names and data types. For example:

  • __time is the suggested timestamp column.
  • continent is a string.
  • session_length is a long format.

At this point you can add or remove columns, adjust the data types, enable rollup, or configure partitioning. For the sake of the tutorial, leave the schema as is.

When you're ready to start your ingestion job, click Start ingestion.

Polaris displays the ingestion job status at the top of the page. When the ingestion job status changes to Ingested, you can start querying your data. This can take a few minutes.

Query data

Query new data:

  1. Return to the Home page, then click SQL in the left sidebar.
  2. Look for the data set you just uploaded by table name, Koalas to the Max. Polaris SQL page
  3. Hover over the table name to display the arrow button. Click on the arrow to populate the SQL QUERY IDE. If you click Run at this stage, you won't get any results since the default query returns data only from the last day.
  4. You can remove the WHERE clause when working with a small amount of data, such as this, but a good practice is to run queries with a time boundary. Replace the default WHERE clause with the following: 
    WHERE "__time" BETWEEN TIMESTAMP '2019-08-19 00:00:00' AND TIMESTAMP '2019-08-21 00:00:00'
  5. Click Run. The query result is similar to the following: Polaris query results

Instead of returning all of the columns in the table, you can select individual columns by name. For example, run the following SQL to show just the cities:

SELECT "city" FROM "Koalas to the Max"
WHERE "__time" BETWEEN TIMESTAMP '2019-08-19 00:00:00' AND TIMESTAMP '2019-08-20 00:00:00'

Add more data

This section explains how to upload files such as clickstream using the API.

  1. Click Tables in the left sidebar.

  2. Click on your table, Koalas to the Max.

  3. Download the gzipped JSON file that contains another day of clickstream activity from KoalasToTheMax.com.

  4. Click Add data.

  5. Choose Upload by API.

  6. Copy the command in the dialog: Polaris API

  7. Open a terminal on your computer and paste the command.

  8. Replace YOUR_FILE with the location of the file you downloaded, kttm-2019-08-20.json.gz. For example:

    curl -H "Accept: application/json" -H "Authorization: Bearer <token>" --url https://api.imply.io/v1/files -F file=@/Users/user/Downloads/kttm-2019-08-20.json.gz

    Note that the example does not show the complete Bearer token.

    Precede the file path with file=@ without any spaces. If you get an error indicating that your request does not contain a file to upload, double check that you've included the @ sign.

  9. Click return to submit the job. If successful, you will receive a JSON response body:

    {
   "id":"00c64ce1-2a12-47f3-9454-eb9cd040a457",
   "name":"kttm-2019-08-20.json.gz",
   "sizeBytes":13800837,
   "dataFormat":"nd-json",
   "compressionFormat":"gz",
   "digest":{
      "algo":"md5",
      "hash":"62D2E21501AA2BCF3F6BC1A5AC21A862"
   },
   "uploadedByUserId":"dbb63d7c-3b35-4268-b351-17e0a98a7bfb",
   "uploadedOnDatetime":"2021-09-29T23:49:43.089995867Z"
}

  10. To see the status of the upload, return to the Polaris interface. Close the API upload window and click Cancel to return to your table.

  11. Click Add data > Choose from uploaded files.

  12. Select the newly uploaded file. Click OK. Polaris choose from files

  13. Click Continue, then click Start ingestion.

  14. When the ingestion job is finished, see if the new data shows up in your query. Return to the Home page and click SQL from the left sidebar.

  15. In the SQL QUERY IDE, use the COUNT() function to get the number of rows from the first day:

SELECT COUNT(*) FROM "Koalas to the Max"
WHERE "__time" BETWEEN TIMESTAMP '2019-08-19 00:00:00' AND TIMESTAMP '2019-08-20 00:00:00'

The query should return 202862.

  1. Extend the time frame to include the second day of data:
SELECT COUNT(*) FROM "Koalas to the Max"
WHERE "__time" BETWEEN TIMESTAMP '2019-08-19 00:00:00' AND TIMESTAMP '2019-08-21 00:00:00'

The query should return 505432.

Visualize data

Visualization features let you explore and draw insights from your data. There are many types of visualizations available in Polaris, including table view, line chart, and heatmap.

Create a data cube

Data cubes contain data from one or more data sources and provide an interface to explore a data set. Make a data cube for Koalas to the Max:

  1. Return to the Home page and click Data cubes from the left sidebar.
  2. Click New data cube.
  3. Select From table as your source and select the table you created, Koalas to the Max. Leave Auto-fill dimensions and measures checked.
  4. Click Next: Create data cube.
  5. Click Save. The data cube appears: Polaris data cube
  6. You can use the data cube to view aggregated data. To view the number of events by country, drag the Country dimension from the left pane into the Show field in the center of the page.

Create a dashboard

Using a dashboard, you can create effective and focused data visualizations. Add a dashboard for the Koalas to the Max data cube:

  1. Return to the Home page and click Dashboards in the left sidebar.
  2. Click New dashboard.
  3. At the top of the page, give your dashboard a name.
  4. With your mouse or pointer, click and drag across blocks on the page to create a new tile.
  5. In the popup, select content type Table.
  6. From the drop-down list, select the data cube Koalas to the Max.
  7. Add a Row for the Country dimension.
  8. Click elsewhere on the page to close the dialog.
  9. Click Create.

That's it! Continue to explore the Polaris UI, try out your own data, or learn more about creating a schema.

← Introduction to Imply PolarisNavigate the console →