Periscope Data Documentation

Connecting to Periscope

First Time Connecting

Connection Definitions

Common Connection Errors

Private Network SSH Tunnels



Getting Started

Keyboard Shortcuts

Charts & Dashboards

Chart Overview

Chart Options

Dashboard Overview

Refresh Mechanics

Organizing Charts

Organizing Dashboards

Table-like Charts

Table Overview

Cohort Grids

Pivot Tables

Graph-like Charts

Overview & General Settings

Chart Types and Settings

Mixing Chart Types

Map Charts

Map Chart Overview


Clusters and Bubbles

Satellite Maps


Other Charts & Customizations

Pie Charts

Image Charts

Chart Annotations

Site Administration

Adding Users

Removing Users

User Types

User Groups

Two-Factor Authentication

Managing User Permissions

Dashboard Permissions

Site Preferences

Query Management

Color Themes

Dashboard Refresh Management

Usage Data

Periscope Cache

Caching Strategies

Querying the Periscope Cache

Cross-Database Joins

CSV Upload

Materializing Views

SQL Formatters

Using SQL Formatters

Composing SQL Formatters

Dollars and Percentages

Time Zone Formatters

Date Aggregation

Date Parts

Basic Filters

Custom Filters

Date Range Filters

Aggregation Filter

Adding, Moving, and Hiding Filters

Advanced Filters

Default Filters


Parent-Child Filters

Matching Filter Values

Time Zone Conversions

Direct Replacement

User Friendly Names


SQL Views

Joining to Views

More SQL Tools

SQL Snippets

Parameterized SQL Snippets

SQL Alerts

Automatic Joins

Version History

Sharing and Embedding

Sharing Dashboards Externally

Email Reports

Easy Embedding

Embed API

Embed API Options

CSV Download

Public CSV URL

Slack API

Slack Linking Reports

Data Management

Adding and Deleting Datasource

Spaces: Data-Level Permissions

Improving Query Throughput

Revoking Table Permissions

Salesforce Datasource

Schema Browser

SSO Integrations




Google Apps

Connection Definitions

SSL JDBC Connection

The easiest way to connect to a database to Periscope is through an SSL JDBC connection. Below is what is needed to get connected.

Database Name or S3 Staging Directory (Athena)

This is the name of the database as it is configured on the database server, or the Amazon S3 location to which the query output is written.

Database Type

Databases connect slightly differently depending on their types so it is important to select the correct database type when connecting a database.

Database Host or Account Name (Snowflake)

The database host is the web address at which Periscope can find the database. The database host needs to be publicly accessible via the internet and accepting connections from the Periscope IP addresses: and Databases that sit within firewall or private network will either need to have traffic from the Periscope IP addresses forwarded to the database or utilize an SSH Tunnel.

Warehouse Name

For Snowflake databases which decouple storage from computation, a warehouse needs to be specified for query processing. Once specified, Periscope will continue to use the same warehouse to run every query.

Database Port

Each database type has a default port through which it accepts connections. If the database has not been configured to use a special port, it is likely accepting connections through these ports:

  • MySQL: 3306
  • Postgres: 5432
  • Redshift: 5439
  • Vertica: 5433
  • SQL Server: 1433
  • Oracle: 1521
  • MemSQL: 3306
  • Sybase: 5000
  • Exasol: 8563

Database Username & Password

This is the username and the corresponding password that Periscope will connect to the database with. Periscope currently supports password authentication to a database and cannot accept connections utilizing public key authentication. It is recommended that a user is created specifically for Periscope to access the database.

SSH Tunnel Connections

If the database is sitting within a private network or behind a firewall an SSH Tunnel is a great way to connect to the database to Periscope. These are the pieces of information required to make that connection.

Database Host

While all other connection components will remain the same as an SSL JDBC connection when connecting using SSH, the database host will now be an internal address that does not have to be publicly accessible.

SSH Host

This is the public facing URL or IP address of the server that is listening for SSH connections.

SSH Username

This is the username that has been created on the SSH host at the operating system level that has been authorized with the Periscope public key. For more information on setting up the SSH host, check out Periscope's Private Network SSH Tunnels docs.

SSH Port

The default SSH port is 22, but if the SSH host server is configured to listen for SSH connections on a different port, that should be entered instead.