mirror of
https://github.com/apache/superset.git
synced 2026-05-08 01:15:46 +00:00
612 lines
35 KiB
HTML
612 lines
35 KiB
HTML
|
||
|
||
<!DOCTYPE html>
|
||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||
<head>
|
||
<meta charset="utf-8">
|
||
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<title>Installation & Configuration — Superset's documentation documentation</title>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="index" title="Index"
|
||
href="genindex.html"/>
|
||
<link rel="search" title="Search" href="search.html"/>
|
||
<link rel="top" title="Superset's documentation documentation" href="index.html"/>
|
||
<link rel="next" title="Tutorial" href="tutorial.html"/>
|
||
<link rel="prev" title="Superset’s documentation" href="index.html"/>
|
||
|
||
|
||
<script src="_static/js/modernizr.min.js"></script>
|
||
|
||
</head>
|
||
|
||
<body class="wy-body-for-nav" role="document">
|
||
|
||
<div class="wy-grid-for-nav">
|
||
|
||
|
||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||
<div class="wy-side-scroll">
|
||
<div class="wy-side-nav-search">
|
||
|
||
|
||
|
||
<a href="index.html" class="icon icon-home"> Superset's documentation
|
||
|
||
|
||
|
||
</a>
|
||
|
||
|
||
|
||
|
||
<div role="search">
|
||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||
<input type="text" name="q" placeholder="Search docs" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
|
||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||
|
||
|
||
|
||
<ul class="current">
|
||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Installation & Configuration</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="#getting-started">Getting Started</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#os-dependencies">OS dependencies</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#python-virtualenv">Python virtualenv</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#python-s-setup-tools-and-pip">Python’s setup tools and pip</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#superset-installation-and-initialization">Superset installation and initialization</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#configuration-behind-a-load-balancer">Configuration behind a load balancer</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#configuration">Configuration</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#database-dependencies">Database dependencies</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#caching">Caching</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#deeper-sqlalchemy-integration">Deeper SQLAlchemy integration</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#schemas-postgres-redshift">Schemas (Postgres & Redshift)</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#ssl-access-to-databases">SSL Access to databases</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#druid">Druid</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#cors">CORS</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#upgrading">Upgrading</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#sql-lab">SQL Lab</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#making-your-own-build">Making your own build</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="security.html">Security</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="security.html#provided-roles">Provided Roles</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="security.html#admin">Admin</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="security.html#alpha">Alpha</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="security.html#gamma">Gamma</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="security.html#managing-gamma-per-data-source-access">Managing Gamma per data source access</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="security.html#customizing">Customizing</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="security.html#permissions">Permissions</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="security.html#restricting-access-to-a-subset-of-data-sources">Restricting access to a subset of data sources</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="security.html#restricting-the-access-to-some-metrics">Restricting the access to some metrics</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="sqllab.html">SQL Lab</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="sqllab.html#feature-overview">Feature Overview</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="sqllab.html#extra-features">Extra features</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="sqllab.html#templating-with-jinja">Templating with Jinja</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="sqllab.html#available-macros">Available macros</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="videos.html">Videos</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="videos.html#quick-intro">Quick Intro</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="videos.html#dashboard-creation">Dashboard Creation</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="videos.html#dashboard-filtering">Dashboard Filtering</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="videos.html#customize-css-and-dashboard-themes">Customize CSS and dashboard themes</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="videos.html#slice-annotations">Slice Annotations</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="videos.html#adding-a-table">Adding a Table</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="videos.html#define-sql-expressions">Define SQL Expressions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="gallery.html">Gallery</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="druid.html">Druid</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="druid.html#supported">Supported</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="druid.html#aggregations">Aggregations</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="druid.html#post-aggregations">Post-Aggregations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="druid.html#not-yet-supported">Not yet supported</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="faq.html#can-i-query-join-multiple-tables-at-one-time">Can I query/join multiple tables at one time?</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="faq.html#how-big-can-my-data-source-be">How BIG can my data source be?</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="faq.html#how-do-i-create-my-own-visualization">How do I create my own visualization?</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="faq.html#why-are-my-queries-timing-out">Why are my queries timing out?</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="faq.html#why-is-the-map-not-visible-in-the-mapbox-visualization">Why is the map not visible in the mapbox visualization?</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="faq.html#how-to-add-dynamic-filters-to-a-dashboard">How to add dynamic filters to a dashboard?</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
|
||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||
|
||
|
||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||
<a href="index.html">Superset's documentation</a>
|
||
</nav>
|
||
|
||
|
||
|
||
<div class="wy-nav-content">
|
||
<div class="rst-content">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||
<ul class="wy-breadcrumbs">
|
||
<li><a href="index.html">Docs</a> »</li>
|
||
|
||
<li>Installation & Configuration</li>
|
||
<li class="wy-breadcrumbs-aside">
|
||
|
||
|
||
|
||
</li>
|
||
</ul>
|
||
<hr/>
|
||
</div>
|
||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||
<div itemprop="articleBody">
|
||
|
||
<div class="section" id="installation-configuration">
|
||
<h1>Installation & Configuration<a class="headerlink" href="#installation-configuration" title="Permalink to this headline">¶</a></h1>
|
||
<div class="section" id="getting-started">
|
||
<h2>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
|
||
<p>Superset is tested using Python 2.7 and Python 3.4+. Python 3 is the recommended version,
|
||
Python 2.6 won’t be supported.</p>
|
||
</div>
|
||
<div class="section" id="os-dependencies">
|
||
<h2>OS dependencies<a class="headerlink" href="#os-dependencies" title="Permalink to this headline">¶</a></h2>
|
||
<p>Superset stores database connection information in its metadata database.
|
||
For that purpose, we use the <code class="docutils literal"><span class="pre">cryptography</span></code> Python library to encrypt
|
||
connection passwords. Unfortunately this library has OS level dependencies.</p>
|
||
<p>You may want to attempt the next step
|
||
(“Superset installation and initialization”) and come back to this step if
|
||
you encounter an error.</p>
|
||
<p>Here’s how to install them:</p>
|
||
<p>For <strong>Debian</strong> and <strong>Ubuntu</strong>, the following command will ensure that
|
||
the required dependencies are installed:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">libssl</span><span class="o">-</span><span class="n">dev</span> <span class="n">libffi</span><span class="o">-</span><span class="n">dev</span> <span class="n">python</span><span class="o">-</span><span class="n">dev</span> <span class="n">python</span><span class="o">-</span><span class="n">pip</span> <span class="n">libsasl2</span><span class="o">-</span><span class="n">dev</span> <span class="n">libldap2</span><span class="o">-</span><span class="n">dev</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>For <strong>Fedora</strong> and <strong>RHEL-derivatives</strong>, the following command will ensure
|
||
that the required dependencies are installed:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">yum</span> <span class="n">upgrade</span> <span class="n">python</span><span class="o">-</span><span class="n">setuptools</span>
|
||
<span class="n">sudo</span> <span class="n">yum</span> <span class="n">install</span> <span class="n">gcc</span> <span class="n">libffi</span><span class="o">-</span><span class="n">devel</span> <span class="n">python</span><span class="o">-</span><span class="n">devel</span> <span class="n">python</span><span class="o">-</span><span class="n">pip</span> <span class="n">python</span><span class="o">-</span><span class="n">wheel</span> <span class="n">openssl</span><span class="o">-</span><span class="n">devel</span> <span class="n">libsasl2</span><span class="o">-</span><span class="n">devel</span> <span class="n">openldap</span><span class="o">-</span><span class="n">devel</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>OSX</strong>, system python is not recommended. brew’s python also ships with pip</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">brew</span> <span class="n">install</span> <span class="n">pkg</span><span class="o">-</span><span class="n">config</span> <span class="n">libffi</span> <span class="n">openssl</span> <span class="n">python</span>
|
||
<span class="n">env</span> <span class="n">LDFLAGS</span><span class="o">=</span><span class="s2">"-L$(brew --prefix openssl)/lib"</span> <span class="n">CFLAGS</span><span class="o">=</span><span class="s2">"-I$(brew --prefix openssl)/include"</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>Windows</strong> isn’t officially supported at this point, but if you want to
|
||
attempt it, download <a class="reference external" href="https://bootstrap.pypa.io/get-pip.py">get-pip.py</a>, and run <code class="docutils literal"><span class="pre">python</span> <span class="pre">get-pip.py</span></code> which may need admin access. Then run the following:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">C</span><span class="p">:</span>\<span class="o">></span> <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span>
|
||
|
||
<span class="c1"># You may also have to create C:\Temp</span>
|
||
<span class="n">C</span><span class="p">:</span>\<span class="o">></span> <span class="n">md</span> <span class="n">C</span><span class="p">:</span>\<span class="n">Temp</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="python-virtualenv">
|
||
<h2>Python virtualenv<a class="headerlink" href="#python-virtualenv" title="Permalink to this headline">¶</a></h2>
|
||
<p>It is recommended to install Superset inside a virtualenv. Python 3 already ships virtualenv, for
|
||
Python 2 you need to install it. If it’s packaged for your operating systems install it from there
|
||
otherwise you can install from pip:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">virtualenv</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You can create and activate a virtualenv by:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># virtualenv is shipped in Python 3 as pyvenv</span>
|
||
<span class="n">virtualenv</span> <span class="n">venv</span>
|
||
<span class="o">.</span> <span class="o">./</span><span class="n">venv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>On windows the syntax for activating it is a bit different:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">venv</span>\<span class="n">Scripts</span>\<span class="n">activate</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Once you activated your virtualenv everything you are doing is confined inside the virtualenv.
|
||
To exit a virtualenv just type <code class="docutils literal"><span class="pre">deactivate</span></code>.</p>
|
||
</div>
|
||
<div class="section" id="python-s-setup-tools-and-pip">
|
||
<h2>Python’s setup tools and pip<a class="headerlink" href="#python-s-setup-tools-and-pip" title="Permalink to this headline">¶</a></h2>
|
||
<p>Put all the chances on your side by getting the very latest <code class="docutils literal"><span class="pre">pip</span></code>
|
||
and <code class="docutils literal"><span class="pre">setuptools</span></code> libraries.:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">setuptools</span> <span class="n">pip</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="superset-installation-and-initialization">
|
||
<h2>Superset installation and initialization<a class="headerlink" href="#superset-installation-and-initialization" title="Permalink to this headline">¶</a></h2>
|
||
<p>Follow these few simple steps to install Superset.:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Install superset</span>
|
||
<span class="n">pip</span> <span class="n">install</span> <span class="n">superset</span>
|
||
|
||
<span class="c1"># Create an admin user</span>
|
||
<span class="n">fabmanager</span> <span class="n">create</span><span class="o">-</span><span class="n">admin</span> <span class="o">--</span><span class="n">app</span> <span class="n">superset</span>
|
||
|
||
<span class="c1"># Initialize the database</span>
|
||
<span class="n">superset</span> <span class="n">db</span> <span class="n">upgrade</span>
|
||
|
||
<span class="c1"># Load some data to play with</span>
|
||
<span class="n">superset</span> <span class="n">load_examples</span>
|
||
|
||
<span class="c1"># Create default roles and permissions</span>
|
||
<span class="n">superset</span> <span class="n">init</span>
|
||
|
||
<span class="c1"># Start the web server on port 8088</span>
|
||
<span class="n">superset</span> <span class="n">runserver</span> <span class="o">-</span><span class="n">p</span> <span class="mi">8088</span>
|
||
|
||
<span class="c1"># To start a development web server, use the -d switch</span>
|
||
<span class="c1"># superset runserver -d</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>After installation, you should be able to point your browser to the right
|
||
hostname:port <a class="reference external" href="http://localhost:8088">http://localhost:8088</a>, login using
|
||
the credential you entered while creating the admin account, and navigate to
|
||
<cite>Menu -> Admin -> Refresh Metadata</cite>. This action should bring in all of
|
||
your datasources for Superset to be aware of, and they should show up in
|
||
<cite>Menu -> Datasources</cite>, from where you can start playing with your data!</p>
|
||
<p>Please note that <em>gunicorn</em>, Superset default application server, does not
|
||
work on Windows so you need to use the development web server.
|
||
The development web server though is not intended to be used on production systems
|
||
so better use a supported platform that can run <em>gunicorn</em>.</p>
|
||
</div>
|
||
<div class="section" id="configuration-behind-a-load-balancer">
|
||
<h2>Configuration behind a load balancer<a class="headerlink" href="#configuration-behind-a-load-balancer" title="Permalink to this headline">¶</a></h2>
|
||
<p>If you are running superset behind a load balancer or reverse proxy (e.g. NGINX
|
||
or ELB on AWS), you may need to utilise a healthcheck endpoint so that your
|
||
load balancer knows if your superset instance is running. This is provided
|
||
at <code class="docutils literal"><span class="pre">/health</span></code> which will return a 200 response containing “OK” if the
|
||
webserver is running.</p>
|
||
<p>If the load balancer is inserting X-Forwarded-For/X-Forwarded-Proto headers, you
|
||
should set <cite>ENABLE_PROXY_FIX = True</cite> in the superset config file to extract and use
|
||
the headers.</p>
|
||
</div>
|
||
<div class="section" id="configuration">
|
||
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2>
|
||
<p>To configure your application, you need to create a file (module)
|
||
<code class="docutils literal"><span class="pre">superset_config.py</span></code> and make sure it is in your PYTHONPATH. Here are some
|
||
of the parameters you can copy / paste in that configuration module:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#---------------------------------------------------------</span>
|
||
<span class="c1"># Superset specific config</span>
|
||
<span class="c1">#---------------------------------------------------------</span>
|
||
<span class="n">ROW_LIMIT</span> <span class="o">=</span> <span class="mi">5000</span>
|
||
<span class="n">SUPERSET_WORKERS</span> <span class="o">=</span> <span class="mi">4</span>
|
||
|
||
<span class="n">SUPERSET_WEBSERVER_PORT</span> <span class="o">=</span> <span class="mi">8088</span>
|
||
<span class="c1">#---------------------------------------------------------</span>
|
||
|
||
<span class="c1">#---------------------------------------------------------</span>
|
||
<span class="c1"># Flask App Builder configuration</span>
|
||
<span class="c1">#---------------------------------------------------------</span>
|
||
<span class="c1"># Your App secret key</span>
|
||
<span class="n">SECRET_KEY</span> <span class="o">=</span> <span class="s1">'</span><span class="se">\2\1</span><span class="s1">thisismyscretkey</span><span class="se">\1\2</span><span class="s1">\e\y\y\h'</span>
|
||
|
||
<span class="c1"># The SQLAlchemy connection string to your database backend</span>
|
||
<span class="c1"># This connection defines the path to the database that stores your</span>
|
||
<span class="c1"># superset metadata (slices, connections, tables, dashboards, ...).</span>
|
||
<span class="c1"># Note that the connection information to connect to the datasources</span>
|
||
<span class="c1"># you want to explore are managed directly in the web UI</span>
|
||
<span class="n">SQLALCHEMY_DATABASE_URI</span> <span class="o">=</span> <span class="s1">'sqlite:////path/to/superset.db'</span>
|
||
|
||
<span class="c1"># Flask-WTF flag for CSRF</span>
|
||
<span class="n">CSRF_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
|
||
|
||
<span class="c1"># Set this API key to enable Mapbox visualizations</span>
|
||
<span class="n">MAPBOX_API_KEY</span> <span class="o">=</span> <span class="s1">''</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This file also allows you to define configuration parameters used by
|
||
Flask App Builder, the web framework used by Superset. Please consult
|
||
the <a class="reference external" href="http://flask-appbuilder.readthedocs.org/en/latest/config.html">Flask App Builder Documentation</a>
|
||
for more information on how to configure Superset.</p>
|
||
<p>Please make sure to change:</p>
|
||
<ul class="simple">
|
||
<li><em>SQLALCHEMY_DATABASE_URI</em>, by default it is stored at <em>~/.superset/superset.db</em></li>
|
||
<li><em>SECRET_KEY</em>, to a long random string</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="database-dependencies">
|
||
<h2>Database dependencies<a class="headerlink" href="#database-dependencies" title="Permalink to this headline">¶</a></h2>
|
||
<p>Superset does not ship bundled with connectivity to databases, except
|
||
for Sqlite, which is part of the Python standard library.
|
||
You’ll need to install the required packages for the database you
|
||
want to use as your metadata database as well as the packages needed to
|
||
connect to the databases you want to access through Superset.</p>
|
||
<p>Here’s a list of some of the recommended packages.</p>
|
||
<table border="1" class="docutils">
|
||
<colgroup>
|
||
<col width="15%" />
|
||
<col width="37%" />
|
||
<col width="49%" />
|
||
</colgroup>
|
||
<thead valign="bottom">
|
||
<tr class="row-odd"><th class="head">database</th>
|
||
<th class="head">pypi package</th>
|
||
<th class="head">SQLAlchemy URI prefix</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody valign="top">
|
||
<tr class="row-even"><td>MySQL</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">mysqlclient</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">mysql://</span></code></td>
|
||
</tr>
|
||
<tr class="row-odd"><td>Postgres</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg2</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">postgresql+psycopg2://</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td>Presto</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pyhive</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">presto://</span></code></td>
|
||
</tr>
|
||
<tr class="row-odd"><td>Oracle</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">cx_Oracle</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">oracle://</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td>sqlite</td>
|
||
<td> </td>
|
||
<td><code class="docutils literal"><span class="pre">sqlite://</span></code></td>
|
||
</tr>
|
||
<tr class="row-odd"><td>Redshift</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">sqlalchemy-redshift</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">redshift+psycopg2://</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td>MSSQL</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pymssql</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">mssql://</span></code></td>
|
||
</tr>
|
||
<tr class="row-odd"><td>Impala</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">impyla</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">impala://</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td>SparkSQL</td>
|
||
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pyhive</span></code></td>
|
||
<td><code class="docutils literal"><span class="pre">jdbc+hive://</span></code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Note that many other database are supported, the main criteria being the
|
||
existence of a functional SqlAlchemy dialect and Python driver. Googling
|
||
the keyword <code class="docutils literal"><span class="pre">sqlalchemy</span></code> in addition of a keyword that describes the
|
||
database you want to connect to should get you to the right place.</p>
|
||
</div>
|
||
<div class="section" id="caching">
|
||
<h2>Caching<a class="headerlink" href="#caching" title="Permalink to this headline">¶</a></h2>
|
||
<p>Superset uses <a class="reference external" href="https://pythonhosted.org/Flask-Cache/">Flask-Cache</a> for
|
||
caching purpose. Configuring your caching backend is as easy as providing
|
||
a <code class="docutils literal"><span class="pre">CACHE_CONFIG</span></code>, constant in your <code class="docutils literal"><span class="pre">superset_config.py</span></code> that
|
||
complies with the Flask-Cache specifications.</p>
|
||
<p>Flask-Cache supports multiple caching backends (Redis, Memcached,
|
||
SimpleCache (in-memory), or the local filesystem). If you are going to use
|
||
Memcached please use the pylibmc client library as python-memcached does
|
||
not handle storing binary data correctly. If you use Redis, please install
|
||
[python-redis](<a class="reference external" href="https://pypi.python.org/pypi/redis">https://pypi.python.org/pypi/redis</a>).</p>
|
||
<p>For setting your timeouts, this is done in the Superset metadata and goes
|
||
up the “timeout searchpath”, from your slice configuration, to your
|
||
data source’s configuration, to your database’s and ultimately falls back
|
||
into your global default defined in <code class="docutils literal"><span class="pre">CACHE_CONFIG</span></code>.</p>
|
||
</div>
|
||
<div class="section" id="deeper-sqlalchemy-integration">
|
||
<h2>Deeper SQLAlchemy integration<a class="headerlink" href="#deeper-sqlalchemy-integration" title="Permalink to this headline">¶</a></h2>
|
||
<p>It is possible to tweak the database connection information using the
|
||
parameters exposed by SQLAlchemy. In the <code class="docutils literal"><span class="pre">Database</span></code> edit view, you will
|
||
find an <code class="docutils literal"><span class="pre">extra</span></code> field as a <code class="docutils literal"><span class="pre">JSON</span></code> blob.</p>
|
||
<a class="reference internal image-reference" href="_images/add_db.png"><img alt="_images/add_db.png" src="_images/add_db.png" style="width: 534.0px; height: 370.8px;" /></a>
|
||
<p>This JSON string contains extra configuration elements. The <code class="docutils literal"><span class="pre">engine_params</span></code>
|
||
object gets unpacked into the
|
||
<a class="reference external" href="http://docs.sqlalchemy.org/en/latest/core/engines.html#sqlalchemy.create_engine">sqlalchemy.create_engine</a> call,
|
||
while the <code class="docutils literal"><span class="pre">metadata_params</span></code> get unpacked into the
|
||
<a class="reference external" href="http://docs.sqlalchemy.org/en/rel_1_0/core/metadata.html#sqlalchemy.schema.MetaData">sqlalchemy.MetaData</a> call. Refer to the SQLAlchemy docs for more information.</p>
|
||
</div>
|
||
<div class="section" id="schemas-postgres-redshift">
|
||
<h2>Schemas (Postgres & Redshift)<a class="headerlink" href="#schemas-postgres-redshift" title="Permalink to this headline">¶</a></h2>
|
||
<p>Postgres and Redshift, as well as other database,
|
||
use the concept of <strong>schema</strong> as a logical entity
|
||
on top of the <strong>database</strong>. For Superset to connect to a specific schema,
|
||
there’s a <strong>schema</strong> parameter you can set in the table form.</p>
|
||
</div>
|
||
<div class="section" id="ssl-access-to-databases">
|
||
<h2>SSL Access to databases<a class="headerlink" href="#ssl-access-to-databases" title="Permalink to this headline">¶</a></h2>
|
||
<p>This example worked with a MySQL database that requires SSL. The configuration
|
||
may differ with other backends. This is what was put in the <code class="docutils literal"><span class="pre">extra</span></code>
|
||
parameter</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="s2">"metadata_params"</span><span class="p">:</span> <span class="p">{},</span>
|
||
<span class="s2">"engine_params"</span><span class="p">:</span> <span class="p">{</span>
|
||
<span class="s2">"connect_args"</span><span class="p">:{</span>
|
||
<span class="s2">"sslmode"</span><span class="p">:</span><span class="s2">"require"</span><span class="p">,</span>
|
||
<span class="s2">"sslrootcert"</span><span class="p">:</span> <span class="s2">"/path/to/my/pem"</span>
|
||
<span class="p">}</span>
|
||
<span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="druid">
|
||
<h2>Druid<a class="headerlink" href="#druid" title="Permalink to this headline">¶</a></h2>
|
||
<ul class="simple">
|
||
<li>From the UI, enter the information about your clusters in the
|
||
<code class="docutils literal"><span class="pre">Admin->Clusters</span></code> menu by hitting the + sign.</li>
|
||
<li>Once the Druid cluster connection information is entered, hit the
|
||
<code class="docutils literal"><span class="pre">Admin->Refresh</span> <span class="pre">Metadata</span></code> menu item to populate</li>
|
||
<li>Navigate to your datasources</li>
|
||
</ul>
|
||
<p>Note that you can run the <code class="docutils literal"><span class="pre">superset</span> <span class="pre">refresh_druid</span></code> command to refresh the
|
||
metadata from your Druid cluster(s)</p>
|
||
</div>
|
||
<div class="section" id="cors">
|
||
<h2>CORS<a class="headerlink" href="#cors" title="Permalink to this headline">¶</a></h2>
|
||
<p>The extra CORS Dependency must be installed:</p>
|
||
<blockquote>
|
||
<div>superset[cors]</div></blockquote>
|
||
<p>The following keys in <cite>superset_config.py</cite> can be specified to configure CORS:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal"><span class="pre">ENABLE_CORS</span></code>: Must be set to True in order to enable CORS</li>
|
||
<li><code class="docutils literal"><span class="pre">CORS_OPTIONS</span></code>: options passed to Flask-CORS (<cite>documentation <http://flask-cors.corydolphin.com/en/latest/api.html#extension></cite>)</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="upgrading">
|
||
<h2>Upgrading<a class="headerlink" href="#upgrading" title="Permalink to this headline">¶</a></h2>
|
||
<p>Upgrading should be as straightforward as running:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">superset</span> <span class="o">--</span><span class="n">upgrade</span>
|
||
<span class="n">superset</span> <span class="n">db</span> <span class="n">upgrade</span>
|
||
<span class="n">superset</span> <span class="n">init</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="sql-lab">
|
||
<h2>SQL Lab<a class="headerlink" href="#sql-lab" title="Permalink to this headline">¶</a></h2>
|
||
<p>SQL Lab is a powerful SQL IDE that works with all SQLAlchemy compatible
|
||
databases out there. By default, queries are run in a web request, and
|
||
may eventually timeout as queries exceed the maximum duration of a web
|
||
request in your environment, whether it’d be a reverse proxy or the Superset
|
||
server itself.</p>
|
||
<p>In the modern analytics world, it’s not uncommon to run large queries that
|
||
run for minutes or hours.
|
||
To enable support for long running queries that
|
||
execute beyond the typical web request’s timeout (30-60 seconds), it is
|
||
necessary to deploy an asynchronous backend, which consist of one or many
|
||
Superset worker, which is implemented as a Celery worker, and a Celery
|
||
broker for which we recommend using Redis or RabbitMQ.</p>
|
||
<p>It’s also preferable to setup an async result backend as a key value store
|
||
that can hold the long-running query results for a period of time. More
|
||
details to come as to how to set this up here soon.</p>
|
||
<p>SQL Lab supports templating in queries, and it’s possible to override
|
||
the default Jinja context in your environment by defining the
|
||
<code class="docutils literal"><span class="pre">JINJA_CONTEXT_ADDONS</span></code> in your superset configuration. Objects referenced
|
||
in this dictionary are made available for users to use in their SQL.</p>
|
||
</div>
|
||
<div class="section" id="making-your-own-build">
|
||
<h2>Making your own build<a class="headerlink" href="#making-your-own-build" title="Permalink to this headline">¶</a></h2>
|
||
<p>For more advanced users, you may want to build Superset from sources. That
|
||
would be the case if you fork the project to add features specific to
|
||
your environment.:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span># assuming $SUPERSET_HOME as the root of the repo
|
||
cd $SUPERSET_HOME/superset/assets
|
||
npm install
|
||
npm run prod
|
||
cd $SUPERSET_HOME
|
||
python setup.py install
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
<footer>
|
||
|
||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||
|
||
<a href="tutorial.html" class="btn btn-neutral float-right" title="Tutorial" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
|
||
|
||
|
||
<a href="index.html" class="btn btn-neutral" title="Superset’s documentation" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
||
|
||
</div>
|
||
|
||
|
||
<hr/>
|
||
|
||
<div role="contentinfo">
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||
|
||
</footer>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
var DOCUMENTATION_OPTIONS = {
|
||
URL_ROOT:'./',
|
||
VERSION:'',
|
||
COLLAPSE_INDEX:false,
|
||
FILE_SUFFIX:'.html',
|
||
HAS_SOURCE: true
|
||
};
|
||
</script>
|
||
<script type="text/javascript" src="_static/jquery.js"></script>
|
||
<script type="text/javascript" src="_static/underscore.js"></script>
|
||
<script type="text/javascript" src="_static/doctools.js"></script>
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript" src="_static/js/theme.js"></script>
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
jQuery(function () {
|
||
SphinxRtdTheme.StickyNav.enable();
|
||
});
|
||
</script>
|
||
|
||
|
||
</body>
|
||
</html> |