docs: Semantic Layer Sync (#6665)

igorlukanin · web-flow · commit b127d06614d0 · 2023-06-06T23:01:51.000+02:00
* docs: Semantic Layer Sync

* Add Metabase workaround

* Remove new env vars

* Remove configuration reference

* Merge pages

* .

* Fixes
diff --git a/docs/content/Configuration/Downstream/Metabase.mdx b/docs/content/Configuration/Downstream/Metabase.mdx
@@ -3,22 +3,30 @@ title: Connecting to Metabase
 permalink: /config/downstream/metabase
 ---
 
-You can connect to Cube from Metabase by using the [Cube SQL API][ref-sql-api].
-Metabase is the easy, open-source way to help everyone in your company work with
-data like an analyst.
+[Metabase][metabase-oss] is an open-source way to help everyone in your
+company to ask questions and learn from data. There's also a fully-managed
+[cloud service][metabase] for Metabase.
 
-Here's a short video guide on how to connect Metabase to Cube.
+## Semantic Layer Sync
 
-<LoomVideo url="https://www.loom.com/embed/38752bb23e5244d1a43675795c470a53" />
+It is recommended to use [Semantic Layer Sync][ref-sls] to connect Cube to
+Metabase. It automatically synchronizes the [data model][ref-data-model]
+between Cube and Metabase.
+
+## SQL API
+
+You can also use the [SQL API][ref-sql-api] to connect Cube to Metabase. 
 
-## Enable Cube SQL API
+<WarningBox>
 
-<InfoBox>
+[Semantic Layer Sync][ref-sls] is the recommended way to connect Metabase to
+Cube. If you're using the SQL API, consider migrating to Semantic Layer Sync.
 
-Don't have a Cube project yet? [Learn how to get started
-here][ref-getting-started].
+</WarningBox>
 
-</InfoBox>
+Here's a short video guide:
+
+<LoomVideo url="https://www.loom.com/embed/38752bb23e5244d1a43675795c470a53" />
 
 ### <--{"id" : "Enable Cube SQL API"}--> Cube Cloud
 
@@ -90,3 +98,8 @@ well.
 
 [ref-getting-started]: /getting-started/cloud/overview
 [ref-sql-api]: /backend/sql
+[metabase-oss]: https://github.com/metabase/metabase
+[metabase]: https://www.metabase.com
+[ref-sls]: /semantic-layer-sync
+[ref-sql-api]: /backend/sql
+[ref-data-model]: /schema/getting-started
diff --git a/docs/content/Configuration/Downstream/Superset.mdx b/docs/content/Configuration/Downstream/Superset.mdx
@@ -5,23 +5,31 @@ redirect_from:
   - /recipes/using-apache-superset-with-cube-sql
 ---
 
-You can connect a Cube project to [Apache Superset][superset] using the Cube SQL
-API. [Apache Superset][superset] is an open-source data exploration and
-visualization platform, commonly used to visualize business metrics and
-performance.
+[Apache Superset][superset] is a popular open-source data exploration
+and visualization platform. [Preset][preset] is a fully-managed service for
+Superset.
 
-Here's a short video guide on how to connect Apache Superset to Cube.
+## Semantic Layer Sync
 
-<LoomVideo url="https://www.loom.com/embed/3e85b7fe3fef4c7bbb8b255ad3f2c675" />
+It is recommended to use [Semantic Layer Sync][ref-sls] to connect Cube to
+Superset or Preset. It automatically synchronizes the
+[data model][ref-data-model] between Cube and Superset or Preset.
+
+## SQL API
+
+You can also use the [SQL API][ref-sql-api] to connect Cube to Superset or Preset. 
 
-## Enable Cube SQL API
+<WarningBox>
 
-<InfoBox>
+[Semantic Layer Sync][ref-sls] is the recommended way to connect Superset or
+Preset to Cube. If you're using the SQL API, consider migrating to Semantic
+Layer Sync.
 
-Don't have a Cube project yet? [Learn how to get started
-here][ref-getting-started].
+</WarningBox>
 
-</InfoBox>
+Here's a short video guide:
+
+<LoomVideo url="https://www.loom.com/embed/3e85b7fe3fef4c7bbb8b255ad3f2c675" />
 
 ### <--{"id" : "Enable Cube SQL API"}--> Cube Cloud
 
@@ -146,3 +154,7 @@ Superset uses loose date ranges when generating SQL queries.
 [superset]: https://superset.apache.org/
 [superset-docs-installation-docker]:
   https://superset.apache.org/docs/installation/installing-superset-using-docker-compose
+[preset]: https://preset.io
+[ref-sls]: /semantic-layer-sync
+[ref-sql-api]: /backend/sql
+[ref-data-model]: /schema/getting-started
diff --git a/docs/content/Reference/Configuration/Config.mdx b/docs/content/Reference/Configuration/Config.mdx
@@ -881,4 +881,4 @@ module.exports = {
 [ref-exec-environment-globals]:
   /schema/reference/execution-environment#node-js-globals-process-env-console-log-and-others
 [ref-environment-variables]: /reference/environment-variables
-[ref-rest-scopes]: /http-api/rest#configuration-api-scopes
+[ref-rest-scopes]: /http-api/rest#configuration-api-scopes
diff --git a/docs/content/Reference/Configuration/Environment-Variables-Reference.mdx b/docs/content/Reference/Configuration/Environment-Variables-Reference.mdx
@@ -688,7 +688,8 @@ The maximum number of partitions each pre-aggregation in a cube can use.
 
 ## `CUBEJS_PG_SQL_PORT`
 
-The port to listen to Postgres-compatible connections on.
+The port used by the [SQL API][ref-sql-api] to listen to Postgres-compatible
+connections on.
 
 | Possible Values     | Default in Development | Default in Production |
 | ------------------- | ---------------------- | --------------------- |
@@ -859,20 +860,27 @@ The path where Cube loads data models from.
 
 ## `CUBEJS_SQL_PASSWORD`
 
-Required password to access SQL API.
+A password required to access the [SQL API][ref-sql-api].
 
 | Possible Values | Default in Development | Default in Production |
 | --------------- | ---------------------- | --------------------- |
 | A valid string  | N/A                    | N/A                   |
 
 ## `CUBEJS_SQL_PORT`
 
-The port to listen to MySQL compatibility connections on.
+The port used by the [SQL API][ref-sql-api] to listen to MySQL-compatible
+connections on.
 
 | Possible Values     | Default in Development | Default in Production |
 | ------------------- | ---------------------- | --------------------- |
 | A valid port number | N/A                    | N/A                   |
 
+<WarningBox>
+
+This environment variable is deprecated. Use `CUBEJS_PG_SQL_PORT` instead.
+
+</WarningBox>
+
 ## `CUBEJS_SQL_SUPER_USER`
 
 A name of specific user who will be allowed to change security context.
@@ -883,7 +891,7 @@ A name of specific user who will be allowed to change security context.
 
 ## `CUBEJS_SQL_USER`
 
-Required username to access SQL API.
+A username required to access the [SQL API][ref-sql-api].
 
 | Possible Values | Default in Development | Default in Production |
 | --------------- | ---------------------- | --------------------- |
@@ -1295,3 +1303,4 @@ The port for a Cube deployment to listen to API connections on.
 [snowflake-docs-warehouse]:
   https://docs.snowflake.com/en/user-guide/warehouses.html
 [wiki-tz-database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+[ref-sql-api]: /backend/sql
diff --git a/docs/content/SQL-API/Overview.mdx b/docs/content/SQL-API/Overview.mdx
@@ -23,7 +23,7 @@ Often, the SQL API is used to enable internal or self-serve
 
 ### <--{"id" : "SQL API"}--> Supported Tools
 
-Cube SQL API has been tested with
+Cube SQL API has been tested with the following tools:
 
 - psql CLI
 - Apache Superset
@@ -42,11 +42,33 @@ Cube SQL API has been tested with
 
 <InfoBox>
 
-Please see [this GitHub issue](https://github.com/cube-js/cube/issues/3906) for
-the tools roadmap and to suggest and vote for tools of your interest.
+Please use [this GitHub issue](https://github.com/cube-js/cube/issues/3906)
+to suggest tools of your interest and vote for already proposed ones.
 
 </InfoBox>
 
+## Configuration
+
+### <--{"id" : "Configuration"}--> Cube Core
+
+SQL API is configured via [environment variables][ref-config-env].
+
+To enable the SQL API, set `CUBEJS_PG_SQL_PORT` to a port number you'd like
+to connect to with a Postgres-compatible tool.
+
+Use `CUBEJS_SQL_USER` and `CUBEJS_SQL_PASSWORD` to configure credentials
+required to connect to the SQL API. You can also use
+[`checkSqlAuth`][ref-config-checksqlauth], [`canSwitchSqlUser`][ref-config-canswitchsqluser],
+and `CUBEJS_SQL_SUPER_USER` to configure [custom authentication][ref-sql-api-auth].
+
+### <--{"id" : "Configuration"}--> Cube Cloud
+
+To enable the SQL API in Cube Cloud, click&nbsp;<Btn>Deploy SQL API</Btn> on
+the&nbsp;<Btn>Overview</Btn> page, then click&nbsp;<Btn>How to connect your BI
+tool</Btn>. You should then see the following screen:
+
+![SQL API details modal|690x428](https://ucarecdn.com/67508334-1641-43ec-9d50-a8f64629992b/)
+
 ## Querying Fundamentals
 
 Under the hood, SQL API uses
@@ -240,14 +262,6 @@ Limit push down is supported by Cube however, a limit over 50,000 can't be
 overridden. In future versions, paging and streaming would be used to avoid this
 limitation.
 
-## Enabling SQL API in Cube Cloud
-
-To enable the SQL API in Cube Cloud, click&nbsp;<Btn>Deploy SQL API</Btn> from
-the&nbsp;<Btn>Overview</Btn> page, then click <Btn>How to connect your BI
-tool</Btn>. You should then see the following screen:
-
-![SQL API details modal|690x428](https://ucarecdn.com/67508334-1641-43ec-9d50-a8f64629992b/)
-
 ## Examples
 
 Consider the following data model:
@@ -519,6 +533,10 @@ WHERE is_completed = true
 
 [ref-config-js]: /config
 [ref-dynamic-schemas]: /schema/dynamic-schema-creation
+[ref-config-env]: /reference/environment-variables
+[ref-sql-api-auth]: /backend/sql/security
+[ref-config-checksqlauth]: /config#options-reference-check-sql-auth
+[ref-config-canswitchsqluser]: /config#options-reference-can-switch-sql-user
 [ref-bi]: /config/downstream#bi-data-exploration-tools
 [ref-superset]: /config/downstream/superset
 [ref-tableau]: /config/downstream/tableau
@@ -528,4 +546,4 @@ WHERE is_completed = true
 [ref-low-code]: /config/downstream#low-code-tools-internal-tool-builders
 [ref-retool]: /config/downstream/retool
 [postgres-protocol]: https://www.postgresql.org/docs/current/protocol.html
-[cube-issbi]: https://cube.dev/use-cases/semantic-layer
+[cube-issbi]: https://cube.dev/use-cases/semantic-layer
diff --git a/docs/content/Workspace/Cube-IDE.mdx b/docs/content/Workspace/Cube-IDE.mdx
@@ -1,5 +1,5 @@
 ---
-title: Cube IDE
+title: Data Model
 permalink: /cloud/workspace/cube-ide
 category: Workspace
 menuOrder: 3
diff --git a/docs/content/Workspace/Development-API.mdx b/docs/content/Workspace/Development-API.mdx
@@ -2,7 +2,7 @@
 title: Development mode
 permalink: /cloud/workspace/development-api
 category: Workspace
-menuOrder: 8
+menuOrder: 11
 ---
 
 Development mode allows to test and debug the data model in an isolated
diff --git a/docs/content/Workspace/Inspecting-Pre-aggregations.mdx b/docs/content/Workspace/Inspecting-Pre-aggregations.mdx
@@ -1,8 +1,8 @@
 ---
-title: Pre-aggregation inspection
+title: Pre-Aggregations
 permalink: /cloud/inspecting-pre-aggregations
 category: Workspace
-menuOrder: 7
+menuOrder: 8
 ---
 
 The Pre-Aggregations page in Cube Cloud allows you to inspect all
diff --git a/docs/content/Workspace/Inspecting-Queries.mdx b/docs/content/Workspace/Inspecting-Queries.mdx
@@ -2,7 +2,7 @@
 title: Query History
 permalink: /cloud/inspecting-queries
 category: Workspace
-menuOrder: 6
+menuOrder: 7
 ---
 
 The Query History screen in Cube Cloud is a one-stop shop for all performance
diff --git a/docs/content/Workspace/SQL-Runner.mdx b/docs/content/Workspace/SQL-Runner.mdx
@@ -2,7 +2,7 @@
 title: SQL Runner
 permalink: /cloud/sql-runner
 category: Workspace
-menuOrder: 4
+menuOrder: 5
 ---
 
 The SQL Runner is a tool that allows you to execute SQL queries from Cube Cloud
diff --git a/docs/content/Workspace/Semantic-Layer-Sync.mdx b/docs/content/Workspace/Semantic-Layer-Sync.mdx
