Data-serving APIs
This section provides all the information you need to query your data. It covers the different query APIs with examples of various data visualizations. It also covers upcoming SQL support.
You can test your GraphQL requests without writing a single line of code in our GraphQL Explorer.
SQL​
In Propel, you can use SQL to query your data. This way, you can easily take advantage of Propel's fast response times, high availability, and access controls with the convenience of familiar SQL syntax.
You can use the SQL API or the PostgreSQL-compatible SQL interface to build your data applications. Learn more about our SQL support.
- GraphQL SQL API
- cURL
- PostgreSQL CLI
query {
sqlV1(input: { query: "SELECT * FROM \"TacoSoft Demo Data\" LIMIT 3" }) {
columns {
columnName
}
rows
}
}
curl -X POST https://api.us-east-2.propeldata.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access Token>" \
-d '{
"query": "query sql($input: SqlV1Input!) { sqlV1( input: $input) { columns { columnName } rows }}",
"variables": {
"input": {
"query": "SELECT * FROM \"TacoSoft Demo Data\" LIMIT 3" }}
}'
psql -h postgres.us-east-2.propeldata.com \
-p 5432 \
-d propel \
-U $PROPEL_APPLICATION_ID \
-W
propel=> SELECT * FROM "TacoSoft Demo Data" LIMIT 3;
Query APIs​
Propel's query APIs are designed for powering various types of visualizations, as well as server-to-server use cases. Each API takes a different input and returns the data in a format optimized for its corresponding visualization.
Time Series​
The Time Series API returns values and labels for every time granule over the requested relative or absolute time range.
GraphQL Time Series example query
- GraphQL query
- Response
Query:
# What was the daily revenue for El Buen Sabor for the last 30 days?
query TimeSeriesExample1($input: TimeSeriesInput!) {
timeSeries(input: $input) {
labels
values
}
}
Variables:
{
"input": {
"metric": {
"sum": {
"dataPool": {
"name": "TacoSoft Demo Data"
},
"measure": {
"columnName": "taco_total_price"
}
}
},
"granularity": "DAY",
"timeRange": {
"relative": "LAST_N_DAYS",
"n": 30
},
"filters": [
{
"column": "restaurant_name",
"operator": "EQUALS",
"value": "El Buen Sabor"
}
]
}
}
{
"data": {
"timeSeries": {
"labels": [
"2023-08-03T00:00:00.000Z",
"2023-08-04T00:00:00.000Z",
"2023-08-05T00:00:00.000Z",
"2023-08-06T00:00:00.000Z",
"2023-08-07T00:00:00.000Z",
"2023-08-08T00:00:00.000Z",
"2023-08-09T00:00:00.000Z",
"2023-08-10T00:00:00.000Z",
"2023-08-11T00:00:00.000Z",
"2023-08-12T00:00:00.000Z",
"2023-08-13T00:00:00.000Z",
"2023-08-14T00:00:00.000Z",
"2023-08-15T00:00:00.000Z",
"2023-08-16T00:00:00.000Z",
"2023-08-17T00:00:00.000Z",
"2023-08-18T00:00:00.000Z",
"2023-08-19T00:00:00.000Z",
"2023-08-20T00:00:00.000Z",
"2023-08-21T00:00:00.000Z",
"2023-08-22T00:00:00.000Z",
"2023-08-23T00:00:00.000Z",
"2023-08-24T00:00:00.000Z",
"2023-08-25T00:00:00.000Z",
"2023-08-26T00:00:00.000Z",
"2023-08-27T00:00:00.000Z",
"2023-08-28T00:00:00.000Z",
"2023-08-29T00:00:00.000Z",
"2023-08-30T00:00:00.000Z",
"2023-08-31T00:00:00.000Z",
"2023-09-01T00:00:00.000Z"
],
"values": [
"0",
"182.25",
"744.25",
"494",
"830.5",
"582.75",
"637",
"347",
"694.75",
"529.5",
"512.75",
"922.25",
"623.5",
"1484.25",
"807.25",
"405.5",
"461.75",
"910.75",
"772",
"681",
"401.75",
"801.25",
"549.5",
"495.25",
"337.5",
"1248.5",
"377",
"544.5",
"553",
"0"
]
}
}
}
Counter​
The Counter API returns a single value for the requested relative or absolute time range.
GraphQL Counter example query
- GraphQL query
- Response
Query:
# Compare the revenue for the last 30 days to the previous 30 days before that
query CounterExample1(
$revenueLast30DaysInput: CounterInput!
$revenuePrevious30DaysInput: CounterInput!
) {
revenueLast30Days: counter(input: $revenueLast30DaysInput) {
value
}
revenuePrevious30Days: counter(input: $revenuePrevious30DaysInput) {
value
}
}
Variables:
{
"revenueLast30DaysInput": {
"metric": {
"sum": {
"dataPool": {
"name": "TacoSoft Demo Data"
},
"measure": {
"columnName": "taco_total_price"
}
}
},
"timeRange": {
"relative": "THIS_MONTH",
"n": null
},
"filters": [
{
"column": "restaurant_name",
"operator": "EQUALS",
"value": "La Taqueria"
}
]
},
"revenuePrevious30DaysInput": {
"metric": {
"sum": {
"dataPool": {
"name": "TacoSoft Demo Data"
},
"measure": {
"columnName": "taco_total_price"
}
}
},
"timeRange": {
"relative": "PREVIOUS_MONTH",
"n": null
},
"filters": [
{
"column": "restaurant_name",
"operator": "EQUALS",
"value": "La Taqueria"
}
]
}
}
{
"data": {
"revenueLast30Days": {
"value": "2940.34"
},
"revenuePrevious30Days": {
"value": "18366.75"
}
}
}
Leaderboard​
The Leaderboard API returns an ordered list of aggregated values grouped by a given dimension.
GraphQL Leaderboard example query
- GraphQL query
- Response
Query:
# Find the top restaurants with the most revenue for the last 30 days.
query LeaderboardExample1($input: LeaderboardInput!) {
leaderboard(input: $input) {
headers
rows
}
}
Variables:
{
"input": {
"metric": {
"sum": {
"dataPool": {
"name": "TacoSoft Demo Data"
},
"measure": {
"columnName": "taco_total_price"
}
}
},
"sort": "DESC",
"timeRange": {
"relative": "LAST_N_DAYS",
"n": 30
},
"rowLimit": 10,
"dimensions": [
{
"columnName": "restaurant_name"
}
],
"filters": []
}
}
{
"data": {
"leaderboard": {
"headers": ["restaurant_name", "value"],
"rows": [
["Farolito", "4064"],
["Los Compadres", "4025.5"],
["Taqueria Cancun", "3835"],
["Taqueria Vallarta", "3736.25"],
["La Taqueria", "3646.75"],
["El Buen Sabor", "3443.5"]
]
}
}
}
Metric Report
The Metric Report API returns one or multiple metrics grouped by a common dimension.
GraphQL Metric Report example query
- GraphQL query
- Response
Query:
# Fetch a report showing the revenue and taco order
# count for the top performing restaurant-taco pairs.
query MetricReportExample($input: MetricReportInput!) {
metricReport(input: $input) {
headers
rows
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
}
}
Variables:
{
"input": {
"timeRange": {
"relative": "LAST_N_DAYS",
"n": 30
},
"dimensions": [
{
"columnName": "restaurant_name"
},
{
"columnName": "taco_name"
}
],
"metrics": [
{
"metric": {
"sum": {
"dataPool": {
"name": "TacoSoft Demo Data"
},
"measure": {
"columnName": "taco_total_price"
}
}
}
},
{
"metric": {
"countDistinct": {
"dataPool": {
"name": "TacoSoft Demo Data"
},
"dimension": {
"columnName": "order_id"
}
}
}
}
],
"orderByColumn": 1,
"first": 10
}
}
{
"data": {
"metricReport": {
"headers": [
"restaurant_name",
"taco_name",
"Revenue",
"Taco Order Count"
],
"rows": [
["El Buen Sabor", "Carne Asada", "2754", "789"],
["El Buen Sabor", "Al Pastor", "2251", "681"],
["El Buen Sabor", "Fish", "2105", "623"],
["Sabor Mexicano", "Shrimp", "2031", "598"],
["Taco Fiesta", "Barbacoa", "1987", "564"],
["Sabor Mexicano", "Chorizo", "1890", "530"],
["Taco Fiesta", "Pollo", "1782", "482"],
["El Buen Sabor", "Veggie", "1542", "377"],
["Sabor Mexicano", "Breakfast", "1523", "412"],
["Taco Fiesta", "Carnitas", "1345", "321"]
],
"pageInfo": {
"startCursor": "eyJvZmZzZXQiOjB9",
"endCursor": "eyJvZmZzZXQiOjl9",
"hasNextPage": true,
"hasPreviousPage": false
}
}
}
}
How to test your GraphQL query​
Once you have a GraphQL query for your data that you want to test, there are a few ways to go about it.
1. GraphQL Explorer​
You can check out our GraphQL Explorer, log in to your Propel account, and test your query there.
2. cURL or a similar tool​
If you'd like to test your query with curl or a similar tool, you can first create an access token like so:
curl -X POST https://auth.us-east-2.propeldata.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
You can find your client ID and secret on Propel Console in the Applications page.
Once you have your access token, you can use it to test your query like this:
curl -X POST https://api.us-east-2.propeldata.com/graphql \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"query": "query LeaderboardExample1($input: LeaderboardInput!) { leaderboard(input: $input) { headers rows }}",
"variables": {
"input": {
"metricName": "Revenue",
"sort": "DESC",
"timeRange": {
"relative": "LAST_N_DAYS",
"n": 30
},
"rowLimit": 10,
"dimensions": [
{
"columnName": "restaurant_name"
}
],
"filters": []
}
}
}'
3. JavaScript​
Here's an example of how you can run a GraphQL query using fetch
in vanilla JavaScript.
const query = `
query LeaderboardExample1($input: LeaderboardInput!) {
leaderboard(input: $input) {
headers
rows
}
}
`
const variables = {
input: {
metricName: 'Revenue',
sort: 'DESC',
timeRange: {
relative: 'LAST_N_DAYS',
n: 30
},
rowLimit: 10,
dimensions: [{ columnName: 'restaurant_name' }],
filters: []
}
}
// Fetch access token
fetch('https://auth.us-east-2.propeldata.com/oauth2/token', {
method: 'post',
body: `grant_type=client_credentials&client_id=${process.env.CLIENT_ID}&client_secret=${process.env.SECRET}`
headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
})
.then((response) => response.json())
.then((jsonData) => jsonData.access_token)
// Post the GraphQL query
.then((access_token) => {
return fetch('https://api.us-east-2.propeldata.com/graphql', {
method: 'POST',
headers: {
Authorization: `Bearer ${access_token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ query, variables })
})
})
.then((response) => response.json())
.then((data) => console.log(data))
In production code, make sure not to expose your client ID and secret on the frontend.
For a more comprehensive example that shows you the whole flow from creating an OAuth 2.0 client, obtaining an access token, and running and processing a GraphQL query, you can check Propel Next.js Starter App.