Merge pull request #5731 from mistercrunch/faq_db_engines

[docs] FAQ entry 'Does Superset work with [database engine]?'

docs/conf.py

@@ -33,7 +33,6 @@ import sphinx_rtd_theme
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
-    'sphinxcontrib.youtube',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/faq.rst

@@ -246,3 +246,55 @@ labels to colors in the ``JSON Metadata`` attribute using the
             "Boys": "#ADD8E6"
         }
     }
+
+Does Superset work with [insert database engine here]?
+------------------------------------------------------
+
+The community over time has curated a list of databases that work well with
+Superset in the :ref:`ref_database_deps` section of the docs. Database
+engines not listed in this page may work too. We rely on the
+community to contribute to this knowledge base.
+
+.. _SQLAlchemy dialect: http://docs.sqlalchemy.org/en/latest/dialects/
+.. _DBAPI driver: https://www.python.org/dev/peps/pep-0249/
+
+For a database engine to be supported in Superset through the
+SQLAlchemy connector, it requires having a Python compliant
+`SQLAlchemy dialect`_ as well as a
+`DBAPI driver`_ defined.
+Database that have limited SQL support may
+work as well. For instance it's possible to connect
+to Druid through the SQLAlchemy connector even though Druid does not support
+joins and subqueries. Another key element for a database to be supported is through
+the Superset `Database Engine Specification
+<https://github.com/apache/incubator-superset/blob/master/superset/db_engine_specs.py>`_
+interface. This interface allows for defining database-specific configurations
+and logic
+that go beyond the SQLAlchemy and DBAPI scope. This includes features like:
+
+
+* date-related SQL function that allow Superset to fetch different
+  time granularities when running time-series queries
+* whether the engine supports subqueries. If false, Superset may run 2-phase
+  queries to compensate for the limitation
+* methods around processing logs and inferring the percentage of completion
+  of a query
+* technicalities as to how to handle cursors and connections if the driver
+  is not standard DBAPI
+* more, read the code for more details
+
+Beyond the SQLAlchemy connector, it's also possible, though much more
+involved, to extend Superset and write
+your own connector. The only example of this at the moment is the Druid
+connector, which is getting superseded by Druid's growing SQL support and
+the recent availability of a DBAPI and SQLAlchemy driver. If the database
+you are considering integrating has any kind of of SQL support, it's probably
+preferable to go the SQLAlchemy route. Note that for a native connector to
+be possible the database needs to have support for running OLAP-type queries
+and should be able to things that are typical in basic SQL:
+
+- aggregate data
+- apply filters (==, !=, >, <, >=, <=, IN, ...)
+- apply HAVING-type filters
+- be schema-aware, expose columns and types
+

docs/installation.rst

@@ -203,7 +203,8 @@ workers this creates a lot of contention and race conditions when defining
 permissions and views.
 
 To alleviate this issue, the automatic updating of permissions can be disabled
-by setting the :envvar:`SUPERSET_UPDATE_PERMS` environment variable to `0`.
+by setting the environment variable
+`SUPERSET_UPDATE_PERMS` environment variable to `0`.
 The value `1` enables it, `0` disables it. Note if undefined the functionality
 is enabled to maintain backwards compatibility.
 
@@ -298,6 +299,9 @@ auth postback endpoint, you can add them to *WTF_CSRF_EXEMPT_LIST*
 
      WTF_CSRF_EXEMPT_LIST = ['']
 
+
+.. _ref_database_deps:
+
 Database dependencies
 ---------------------
 
@@ -704,7 +708,7 @@ Note that it's also possible to implement you own logger by deriving
 
 
 Install Superset with helm in Kubernetes
---------------
+----------------------------------------
 
 You can install Superset into Kubernetes with Helm <https://helm.sh/>. The chart is
 located in ``install/helm``.
@@ -727,7 +731,6 @@ The first step: Configure authorization in Superset ``superset_config.py``.
 .. code-block:: python
 
     AUTH_TYPE = AUTH_OAUTH
-    
     OAUTH_PROVIDERS = [
         {   'name':'egaSSO',
             'token_key':'access_token', # Name of the token in the response of access_token_url

docs/requirements.txt

@@ -1,3 +1,2 @@
 sphinx==1.7.1
 sphinx-rtd-theme==0.2.4
-sphinxcontrib.youtube==0.1.2