[GitHub] betodealmeida closed pull request #5731: [docs] FAQ entry 'Does Superset work with [database engine]?'

[GitBox <gi...@apache.org>]

betodealmeida closed pull request #5731: [docs] FAQ entry 'Does Superset work with [database engine]?'
URL: https://github.com/apache/incubator-superset/pull/5731
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/docs/conf.py b/docs/conf.py
index f78a9a420c..d1c72a9e3a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -33,7 +33,6 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
-    'sphinxcontrib.youtube',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/faq.rst b/docs/faq.rst
index 63f4f72936..3b69044563 100644
--- a/docs/faq.rst
+++ b/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
+
diff --git a/docs/installation.rst b/docs/installation.rst
index 008a2648f1..6b08b82ab3 100644
--- a/docs/installation.rst
+++ b/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
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 748df23c7c..99f31cac65 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,2 @@
 sphinx==1.7.1
 sphinx-rtd-theme==0.2.4
-sphinxcontrib.youtube==0.1.2


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org