Skip to main content

Quickstart 🌮

Get started with Propel in 5 minutes​

This guide explains how to set up Propel in under 5 minutes. We will go over how to:

  1. Create a Propel account
  2. Create a Data Source and Data Pool with sample data
  3. Define a Metric
  4. Query the data
  5. Create a Propel Application and get the API credentials
  6. Run the Propel Next.js Starter App

At Propel, we love tacos. So our demo data for the quickstart is “TacoSoft”, an imaginary SaaS application for taquerias to sell tacos 🌮!

Let's get started 🚀

1. Create a Propel account​

Creating a Propel account is straightforward. Navigate to the sign-up page, provide an email, provide a password, and select your data residency region. Accept the Terms of Service and click "Get Started".

👋🏼Request access

You need an invite to create a Propel account. If you don't have one, please request access.


Propel Account set up step 1

Propel Account set up step 2

You will receive a confirmation email. Click on the link to confirm your email and log in again.

Propel Account set up step 3

Once you log in, your account will be created, and you will land in the Propel Console.

Propel Account set up step 4

2. Create a Data Source and Data Pool with sample data​

Next, we need to get the TacoSoft data into Propel.

Go to Data Sources, then click “Create new Data Source”. You will see all Data Sources supported, as well as the “TacoSoft Demo Data”.

Propel Data Source set up step 1

Select the “TacoSoft Demo Data” Data Source. This Data Source will automatically create an Amazon S3 Data Source provisioned with the TacoSoft data that you can use.

Propel Data Source set up step 2

Once you create it, you will see the “TacoSoft Demo Data” Data Source.

Propel Data Source set up step 3

Next, we are going to create a Data Pool with our TacoSoft Data Source. A Data Pool will sync the data from TacoSoft's Data Lake in S3 into high-speed storage and cache so it can be served to your application via the API.

Go to the Data Pool section and click “Create Data Pool”. Enter the following information:

  • Give your Data Pool a unique name like: “TacoSoft Sales Data”.
  • Give your Data Pool a description like: “TacoSoft order items records.”
  • Select the “TacoSoft Demo Data” Data Source.
  • Select the “TacoSoft Demo Data” table.
  • Click “Next”.

Propel Data Pool set up step 1

In the next step, you will see the table schema. It will have a list of columns, the source type, and the suggested Propel data type. Here you can control how data types are mapped from the data source into Propel. For the sample data, you don't need to change anything in this step. You can click next.

Propel Data Pool set up step 2

The last step to creating your Data Pool is to select the primary timestamp column, the tenant ID, and the Sync Interval.

For the timestamp column, we want to select the column that indicates when the record was created. For the TacoSoft demo data, it is the column named timestamp.

The sync interval specifies how often the data is synced from the underlying data source to Propel. For our TacoSoft demo data, we want to select EVERY_1_HOUR since new demo data is generated every hour.

The tenant ID specifies the tenant identifier for multi-tenant applications that you can use to control access to your data. Although our TacoSoft data represents a multi-tenant SaaS application and has a tenant identified (the restaurant_id column), for the purposes of the quickstart, we are not going to define a tenant ID.

Click “Create Data Pool”.

Propel Data Pool set up step 3

When you create the Data Pool, Propel connects to the underlying data lake in Amazon S3 and starts syncing the data.

Propel Data Pool set up step 4

Once all the checks are green, click “View sync activity”. This initial sync can take a couple of minutes. Once the first Sync completes, you will see it as “Succeeded,” and you'll see the number of records it synced. Every hour you will see a new sync with new data coming in.

Propel Data Pool set up step 5

In the “Schema” tab, you can see the data schema.

Propel Data Pool set up step 6

And on the “Preview” tab, you can see the actual data.

Propel Data Pool set up step 7

3. Define a Metric​

Now that you have loaded the TacoSoft demo data into your Propel account, you can model it into a metric representing a business key performance indicator (KPI).

For our quickstart, we are going to create a “Revenue” metric to uncover insights about our taco sales. We not only want to see taco sales over time but also want to be able to filter and break the revenue down by restaurant name, taco name, sauce name, toppings, and tortilla name.

Go to the Metrics section and click “Create Metric”. Enter the following information:

  • Give your Metric a unique name: “Revenue”
  • Give your Metric a description: “The taco sales in dollars. Sums the taco_total_price of order items.”
  • Select the “TacoSoft Sales Data” Data Pool to power your Metric.
  • Select the “SUM” Metric type. Once you select the “SUM” type, you'll be prompted to select a measure that represents the column you need to sum.
  • To represent sales, we'd want to sum the taco_total_price column.
  • You can optionally add filters if you need to exclude certain records from the sum calculation. For our quickstart, we are going to leave the metric without filters.
  • Click “Next”.

Propel Metric definition step 1

Next, we’ll want to select the Data Pool columns that we want to have as dimensions on our metric to break down and filter by. Select the taco_name, sauce_name, restaurant_name, tortilla_name, and toppings columns.

Propel Metric definition step 1

Once your Metric is created, you’ll see that you don’t have any query activity yet. This is expected behavior.

Propel Metric definition step 1

4. Query the data​

Now that you have a Data Pool with data and a Metric defined, let’s query it!

While on the “Revenue” Metric, click on the “Playground” tab, then click “Run Query”.

The Playground will help you explore the data, and on the right-hand side, it will show you the GraphQL API request for that query. You can try out the different queries: Time Series, Counter, and Leaderboard.

Propel query data

🎉 🍾🎈 You’ve made your first query!

5. Create a Propel Application and get the API credentials​

Next, you’ll want to make queries from an application. You'll need to create a Propel Application to make API requests to Propel from your application. Propel Applications provides the API credentials allowing your client- or server-side app to access the Propel API.

Go to the Applications section and click “Create Application”. Enter the following information:

  • Give your Application a unique name: “TacoSoft App”
  • Give your Application a description: “The TacoSoft sample app.”
  • For the API scopes, you’ll want your Propel Application to have the “METRIC_QUERY” and “METRIC_READ” scopes. This allows your app to list the available metrics and query their data.
  • The Propeller is the serverless compute for your Propel Application. The larger the compute, the faster the queries. For our Quickstart, you can select “P1_X1_SMALL”.
  • Click “Create”

Create a Propel Application

6. Run the Propel Next.js Starter App​

The Propel Next.js Starter App is a simple web application that demonstrates how to use the Propel GraphQL API and our open-source UI Kit library to display data visualizations in a web browser. Install it using the following commands.

First, clone the repo for the Propel Next.js Starter App:

git clone https://github.com/propeldata/propel-nextjs-starter-app.git

or

gh repo clone propeldata/propel-nextjs-starter-app

Once you’ve cloned the repo, cd into its directory:

cd propel-nextjs-starter-app

You’ll need to set your Propel Application’s client ID and secret in a .env.local file. To do this, first make a copy of the .env.sample included in the app’s root directory:

cp .env.local.sample .env.local

Then, update the .env.local file to include your Propel Application’s client ID and secret:

CLIENT_ID=1jb…
CLIENT_SECRET=1og…

Install dependencies:

npm install

Now you are good to run the app locally!

npm start

Go to http://localhost:3000. Select the “Revenue” metric you created.

Propel Starter App

Then click on the different visualizations to learn different ways to visualize the data.

Propel Starter App - Time Series

Propel Starter App - Leaderboard

Now you have a working Next.js app serving data from Propel.