From 221e03eea8c708374aedd8a1b3f6a95359c9c18b Mon Sep 17 00:00:00 2001 From: Hassan Khan Date: Mon, 16 Jan 2023 16:15:53 +0000 Subject: [PATCH 01/13] docs(getting-started): revamp Getting Started guide for Cloud and Open Source --- .../Configuration/Downstream/Superset.mdx | 1 - .../Getting-Started/Cloud/01-Overview.mdx | 25 ++ .../Cloud/02-Create-a-deployment.mdx | 130 +++++++ .../Cloud/03-Generate-models.mdx | 100 +++++ .../Getting-Started/Cloud/04-Query-data.mdx | 150 ++++++++ .../Cloud/05-Add-a-pre-aggregation.mdx | 54 +++ .../Getting-Started/Cloud/06-Learn-more.mdx | 36 ++ .../Getting-Started/Core/01-Overview.mdx | 25 ++ .../Core/02-Create-a-project.mdx | 125 +++++++ .../Core/03-Generate-models.mdx | 44 +++ .../Getting-Started/Core/04-Query-data.mdx | 102 +++++ .../Core/05-Add-a-pre-aggregation.mdx | 54 +++ .../Getting-Started/Core/06-Learn-more.mdx | 41 ++ .../Getting-Started-Docker-Compose.mdx | 106 ------ .../Getting-Started-Docker.mdx | 98 ----- .../Getting-Started-Nodejs.mdx | 353 ------------------ docs/content/Getting-Started/Overview.mdx | 30 +- docs/content/SQL-API/Getting-Started.mdx | 73 ---- docs/content/Schema/Getting-Started.mdx | 293 --------------- 19 files changed, 902 insertions(+), 938 deletions(-) create mode 100644 docs/content/Getting-Started/Cloud/01-Overview.mdx create mode 100644 docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx create mode 100644 docs/content/Getting-Started/Cloud/03-Generate-models.mdx create mode 100644 docs/content/Getting-Started/Cloud/04-Query-data.mdx create mode 100644 docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx create mode 100644 docs/content/Getting-Started/Cloud/06-Learn-more.mdx create mode 100644 docs/content/Getting-Started/Core/01-Overview.mdx create mode 100644 docs/content/Getting-Started/Core/02-Create-a-project.mdx create mode 100644 docs/content/Getting-Started/Core/03-Generate-models.mdx create mode 100644 docs/content/Getting-Started/Core/04-Query-data.mdx create mode 100644 docs/content/Getting-Started/Core/05-Add-a-pre-aggregation.mdx create mode 100644 docs/content/Getting-Started/Core/06-Learn-more.mdx delete mode 100644 docs/content/Getting-Started/Getting-Started-Docker-Compose.mdx delete mode 100644 docs/content/Getting-Started/Getting-Started-Docker.mdx delete mode 100644 docs/content/Getting-Started/Getting-Started-Nodejs.mdx delete mode 100644 docs/content/SQL-API/Getting-Started.mdx delete mode 100644 docs/content/Schema/Getting-Started.mdx diff --git a/docs/content/Configuration/Downstream/Superset.mdx b/docs/content/Configuration/Downstream/Superset.mdx index eaaf41a9b21ac..a64f8f19a8262 100644 --- a/docs/content/Configuration/Downstream/Superset.mdx +++ b/docs/content/Configuration/Downstream/Superset.mdx @@ -135,7 +135,6 @@ To allow queries from Superset to match pre-aggregations in Cube, [the must be set to `true` in the pre-aggregation definition. This is because Superset uses loose date ranges when generating SQL queries. -[ref-cube-getting-started-docker]: https://cube.dev/docs/getting-started/docker [ref-getting-started]: /cloud/getting-started [ref-schema-ref-preagg-allownonstrict]: /schema/reference/pre-aggregations#allow-non-strict-date-range-match diff --git a/docs/content/Getting-Started/Cloud/01-Overview.mdx b/docs/content/Getting-Started/Cloud/01-Overview.mdx new file mode 100644 index 0000000000000..eee3b53ee56c4 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/01-Overview.mdx @@ -0,0 +1,25 @@ +--- +title: Overview +permalink: /getting-started/cloud/overview +category: Getting Started +subCategory: Cube Cloud +menuOrder: 2 +isDisableFeedbackBlock: true +--- + +To get started with Cube Cloud, first we'll create a new deployment, connect it +to a database and generate models from it. Then we'll query Cube using the +Developer Playground and APIs. Finally, we'll add a pre-aggregation to optimize +query latency down to milliseconds. + +This guide will walk you through each task: + +- [Create a new deployment](/getting-started/cloud/create-a-deployment) +- [Generate models from a connected data source](/getting-started/cloud/generate-models) +- [Query Cube using the Developer Playground and APIs](/getting-started/cloud/query-data) +- [Add a pre-aggregation to optimize query performance](/getting-started/cloud/add-a-pre-aggregation) + +If you'd prefer to run Cube locally, then you can refer to [Getting Started +using Cube Core][ref-getting-started-core-overview] instead. + +[ref-getting-started-core-overview]: /getting-started/core/overview diff --git a/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx new file mode 100644 index 0000000000000..830b19967b0d6 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx @@ -0,0 +1,130 @@ +--- +title: Create a deployment +permalink: /getting-started/cloud/create-a-deployment +category: Getting Started +subCategory: Cube Cloud +menuOrder: 3 +isDisableFeedbackBlock: true +--- + + + +To continue with this guide, you'll need to have a Cube Cloud account. If you +don't have one yet, [click here to sign up][cube-cloud-signup] for free. + + + +In this step, we will create a new deployment in Cube Cloud. Deployments +represent a project, and we will use it to connect our data source and generate +models. + +## Create deployment + +The first step in creating a deployment is to [sign in to your Cube Cloud +account][cube-cloud-signin]. After signing in, click the **Create Deployment** +button: + +
+ Cube Cloud Landing Screen with no configured deployments +
+ +Give the deployment a name and select the cloud provider and region of your +choice and click **Next**: + +
+ Cube Cloud Create Deployment Screen +
+ +## Set up Cube project + +Next, click **Create** to create a new project from scratch: + +
+ Cube Cloud Upload Project Screen +
+ +## Connect a data source + +The last step in creating a deployment is to connect your data source to Cube +Cloud. + + + +Want to use a sample database instead? Use the credentials below: + +
+ +| Field | Value | +| -------- | ------------------ | +| Host | `demo-db.cube.dev` | +| Port | `5432` | +| Database | `ecom` | +| Username | `cube` | +| Password | `12345` | + + + +To do this, first select **PostgreSQL** as the data source: + +
+ Cube Cloud Setup Database Screen +
+ +After selecting the data source, enter valid credentials for it and click +**Apply**. Check the [Connecting to Databases][ref-conf-db] page for more +details on specific data sources. + +
+ Cube Cloud Setup Database Screen +
+ +If you run into issues here, make sure to allow inbound connections from Cube +Cloud IP addresses to your database. This means you need to enable these IPs in +your firewall. Using the screenshot in the example above, if you are using AWS, +this would mean adding new [rules][aws-docs-sec-group-rule] to your database's +[security group][aws-docs-sec-group]: + +| Source | Protocol | Port range | +| --------------- | -------- | ---------- | +| `3.65.255.79` | `TCP` | `5432` | +| `3.69.4.168` | `TCP` | `5432` | +| `3.64.153.169` | `TCP` | `5432` | +| `18.185.128.84` | `TCP` | `5432` | + +Now that the deployment is configured, we can move on to [generating models from +our data source][ref-getting-started-cloud-generate-models]. + +[aws-docs-sec-group]: + https://docs.aws.amazon.com/vpc/latest/userguide/security-groups.html +[aws-docs-sec-group-rule]: + https://docs.aws.amazon.com/vpc/latest/userguide/security-group-rules.html +[cube-cloud-signin]: https://cubecloud.dev/auth +[cube-cloud-signup]: https://cubecloud.dev/auth/signup +[ref-conf-db]: /config/databases +[ref-getting-started-cloud-generate-models]: + /getting-started/cloud/generate-models diff --git a/docs/content/Getting-Started/Cloud/03-Generate-models.mdx b/docs/content/Getting-Started/Cloud/03-Generate-models.mdx new file mode 100644 index 0000000000000..b4d7ec9a4d0dd --- /dev/null +++ b/docs/content/Getting-Started/Cloud/03-Generate-models.mdx @@ -0,0 +1,100 @@ +--- +title: Generate models +permalink: /getting-started/cloud/generate-models +category: Getting Started +subCategory: Cube Cloud +menuOrder: 4 +isDisableFeedbackBlock: true +--- + +In this step, you will generate models using the connected data source from the +last step. Cube's models provide a declarative way to define important facts +about your data, relationships between them and access control. + +## Select tables + +Start by selecting the database tables to generate the data schema from, then +click **Measures and Dimensions**: + +
+ Cube Cloud Generate Models Screen detected tables from data source for selection +
+ +## Measures and dimensions + +Next, you'll see all detected measures and dimensions from the data source. +Click **Primary Keys** to progress to the next step: + +
+ Cube Cloud Generate Models Screen showing detected measures and dimensions +
+ +## Primary keys + +Review the detected primary keys for each cube and click **Joins** to move to +the next step: + +
+ Cube Cloud Generate Models Screen showing detected primary keys +
+ +## Joins + +Once again, review the detected joins and click **Review**: + +
+ Cube Cloud Generate Models Screen showing detected joins +
+ +## Review + +The last screen allows you to review all the detected cubes and their +corresponding measures, dimensions and joins. If everything looks good, pick +either YAML or JavaScript for the model's syntax and click **Confirm & +Generate**: + +
+ Cube Cloud Generate Models Screen showing review screen +
+ +Cube Cloud will now generate the models and spin up your Cube deployment, and in +a few moments you should see the following screen: + +
+ Cube Cloud Deployment Overview Screen +
+ +You're now ready for the last step, [querying the data source via the Cube +API][ref-getting-started-cloud-query-cube]. + +[ref-getting-started-cloud-query-cube]: /getting-started/cloud/query-data diff --git a/docs/content/Getting-Started/Cloud/04-Query-data.mdx b/docs/content/Getting-Started/Cloud/04-Query-data.mdx new file mode 100644 index 0000000000000..4fd5d61608181 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/04-Query-data.mdx @@ -0,0 +1,150 @@ +--- +title: Query data +permalink: /getting-started/cloud/query-data +category: Getting Started +subCategory: Cube Cloud +menuOrder: 5 +isDisableFeedbackBlock: true +--- + +In this step, you will learn how to query your data using the models you created +in the previous step. Cube Cloud provides several ways to query your data, and +we'll go over them here. + +## Developer Playground + +The Playground is a web-based tool that allows you to query your data without +writing any code. It's a great way to get started with Cube and explore your +data. + +To open the Playground, open the **Playground** page in Cube Cloud: + +
+ Cube Cloud Deployment Developer Playground Screen +
+ +Next, you will select the measures and dimensions you want to query, and then +run the query. Let's do this for the `Orders` cube you generated in the previous +step. + +Click **+ Measure** to display the available measures and add `Orders.count`, +then click **Run**: + +
+ Cube Cloud Deployment Developer Playground Screen with a selected measure +
+ +Next, click **+ Dimension** for available dimensions and add `Orders.status` and +then click **Run** again: + +
+ Cube Cloud Deployment Developer Playground Screen with selected measures and dimensions +
+ +## GraphQL API + +From the deployment's Overview page, you can copy the GraphQL API URL for the +deployment: + +
+ Cube Cloud Deployment Overview Screen +
+ +To see an example of how to query the GraphQL API using cURL, click **How to +connect your application**: + +
+ Cube Cloud Deployment Screen with How to connect your application over GraphQL dialog open +
+ +## REST API + +
+ Cube Cloud Deployment Overview Screen +
+ +To see an example of how to query the REST API using cURL, click **How to +connect your application**: + +
+ Cube Cloud Deployment Screen with How to connect your application over REST dialog open +
+ +## SQL API + +On the Overview page, click **How to connect**, which will open a modal with +instructions on different ways to connect to the SQL API. Navigate to the SQL +API tab and enable the SQL API. + +Once it is enabled, you should see a screen like the one below with your +connection credentials: + +
+ +
+ +We can test it by running the provided `psql` command: + +```bash{outputLines: 2-14} +PGPASSWORD=c9fba08a9b41f69f698b00134587d325 \ + psql -h fierce-bear.sql.aws-eu-central-1.cubecloudapp.dev \ + -p 5432 \ + -U cube fierce-bear + +psql (14.5, server 14.2 (Cube SQL)) +SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off) +Type "help" for help. + +fierce-bear=> SELECT COUNT(*) FROM Orders; + COUNT(UInt8(1)) +----------------- + 10000 +(1 row) +``` + +Since the Cube SQL API is Postgres-compatible, please make sure to select +**Postgres** as the database type when connecting from BI tools. + +Now that we've seen how to query Cube across its APIs, let's take a look at [how +to add pre-aggregations to your deployment to speed up your queries][next]. + +[next]: /getting-started/cloud/add-a-pre-aggregation diff --git a/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx b/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx new file mode 100644 index 0000000000000..432d67ccf06ef --- /dev/null +++ b/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx @@ -0,0 +1,54 @@ +--- +title: Add a pre-aggregation +permalink: /getting-started/cloud/add-a-pre-aggregation +category: Getting Started +subCategory: Cube Cloud +menuOrder: 6 +isDisableFeedbackBlock: true +--- + +In this step, we'll add a pre-aggregation to optimize the performance of a +specific query. Pre-aggregations are a caching technique that massively reduces +query time from seconds to milliseconds, and are extremely useful for speeding +up queries that are run frequently. + +From the Developer Playground, execute a query: + +
+ Cube Cloud Deployment Developer Playground Screen showing query results +
+ +Just above the results, click on **Query was not accelerated with +pre-aggregation** to bring up the Rollup Designer: + +
+ Cube Cloud Deployment Developer Playground Screen showing Rollup Designer +
+ +The Rollup Designer will automatically suggest a pre-aggregation for the query; +simply click **Add to the Data Schema** and then retry the query in the +Playground. This time, the query should be accelerated with a pre-aggregation: + +
+ Cube Cloud Deployment Developer Playground Screen querying a pre-aggregation +
+ +And with that, we conclude our Getting Started with Cube Cloud guide. If you'd +like to learn more about Cube Cloud, [check out this page][next]. + +[next]: /getting-started/cloud/learn-more diff --git a/docs/content/Getting-Started/Cloud/06-Learn-more.mdx b/docs/content/Getting-Started/Cloud/06-Learn-more.mdx new file mode 100644 index 0000000000000..dcbcd6360de98 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/06-Learn-more.mdx @@ -0,0 +1,36 @@ +--- +title: Learn more +permalink: /getting-started/cloud/learn-more +category: Getting Started +subCategory: Cube Cloud +menuOrder: 7 +isDisableFeedbackBlock: true +--- + +Now that you've set up your first deployment, learn more about what else Cube +Cloud can do for you. + +## Access Control + +Cube Cloud enhances the existing security available in open-source and adds +[role-based access control](/cloud/access-control/) to secure the Cube Cloud UI +and individual deployments. + +## Alerts and Observability + +The [Queries](/cloud/inspecting-queries) page in Cube Cloud provides query-level +observability, allowing for easy diagnosis of performance issues and remedying +them with pre-aggregations where possible. + +Cube Cloud also allows [setting up alerts](/cloud/workspace/alerts), so you can +be notified if something goes wrong with your deployment. + +## Team collaboration + +Cube Cloud allows you to invite other users to your account and manage their +access to your deployments. You can also create and manage multiple deployments, +each with their own set of users. + +Cube Cloud has [a web-based IDE](/cloud/workspace/cube-ide) that can be used to +make changes to models and test them in a development environment. You can also +connect [Cube Cloud to Git](/cloud/deploys) to allow for easy collaboration. diff --git a/docs/content/Getting-Started/Core/01-Overview.mdx b/docs/content/Getting-Started/Core/01-Overview.mdx new file mode 100644 index 0000000000000..5f2eab620e2cd --- /dev/null +++ b/docs/content/Getting-Started/Core/01-Overview.mdx @@ -0,0 +1,25 @@ +--- +title: Overview +permalink: /getting-started/core/overview +category: Getting Started +subCategory: Core +menuOrder: 3 +isDisableFeedbackBlock: true +--- + +To get started with Cube Cloud, first we'll create a new deployment, connect it +to a database and generate models from it. Then we'll query Cube using the +Developer Playground and APIs. Finally, we'll add a pre-aggregation to optimize +query latency down to milliseconds. + +This guide will walk you through the following tasks: + +- [Create a new project](/getting-started/core/create-a-project) +- [Generate models from a connected data source](/getting-started/core/generate-models) +- [Query Cube using the Developer Playground and APIs](/getting-started/core/query-data) +- [Add a pre-aggregation to optimize query performance](/getting-started/core/add-a-pre-aggregation) + +If you'd prefer to try Cube Cloud, then you can refer to [Getting Started using +Cube Cloud][ref-getting-started-cloud-overview] instead. + +[ref-getting-started-cloud-overview]: /getting-started/cloud/overview diff --git a/docs/content/Getting-Started/Core/02-Create-a-project.mdx b/docs/content/Getting-Started/Core/02-Create-a-project.mdx new file mode 100644 index 0000000000000..6e270e7fdcab3 --- /dev/null +++ b/docs/content/Getting-Started/Core/02-Create-a-project.mdx @@ -0,0 +1,125 @@ +--- +title: Create a project +permalink: /getting-started/core/create-a-project +category: Getting Started +subCategory: Core +menuOrder: 4 +isDisableFeedbackBlock: true +--- + +## Scaffold a project + +Start by opening your terminal to create a new folder for the project, then +create a `docker-compose.yml` file within it: + +```bash{promptUser: user} +mkdir my-first-cube-project && cd $_ +touch docker-compose.yml +``` + +Open the `docker-compose.yml` file and add the following content: + + + +If you're using Linux as the Docker host OS, you'll also need to add +`network_mode: 'host'` to your `docker-compose.yml`. + + + +```yaml +version: '2.2' + +services: + cube: + image: cubejs/cube:latest + ports: + - 4000:4000 + environment: + - CUBEJS_DEV_MODE=true + volumes: + - .:/cube/conf +``` + +## Start the development server + + + +Using Windows? Remember to use [PowerShell][powershell-docs] or +[WSL2][wsl2-docs] to run the command below. + + + +From the newly-created project directory, run the following command to start +Cube: + +```bash{promptUser: user} +docker-compose up -d +``` + +## Connect a data source + +Head to [http://localhost:4000](http://localhost:4000) to open [Developer +Playground][ref-devtools-playground]. + +The [Developer Playground][ref-devtools-playground] has a database connection +wizard that loads when Cube is first started up and no `.env` file is found. +After database credentials have been set up, an `.env` file will automatically +be created and populated with the same credentials. + +
+ +
+ +The next screen shows all the databases Cube can connect to. Click on +**PostgreSQL**, then use the following credentials: + +| Field | Value | +| -------- | ------------------ | +| Host | `demo-db.cube.dev` | +| Port | `5432` | +| Database | `ecom` | +| Username | `cube` | +| Password | `12345` | + +
+ +
+ +After clicking Apply, you should see tables available to you from the configured +database; select the `orders` table to generate a Cube model: + +
+ +
+ +After selecting the table, click **Generate Schema** and you should see the +following: + +
+ +
+ +Click **Build** on the dialog, which should take you to the **Build** page. + +In the next step, we'll learn how to +[create a model from scratch](/getting-started/core/create-models). + +[powershell-docs]: https://learn.microsoft.com/en-us/powershell/ +[ref-devtools-playground]: /dev-tools/dev-playground +[wsl2-docs]: https://learn.microsoft.com/en-us/windows/wsl/install diff --git a/docs/content/Getting-Started/Core/03-Generate-models.mdx b/docs/content/Getting-Started/Core/03-Generate-models.mdx new file mode 100644 index 0000000000000..e48df39bcfefc --- /dev/null +++ b/docs/content/Getting-Started/Core/03-Generate-models.mdx @@ -0,0 +1,44 @@ +--- +title: Generate models +permalink: /getting-started/core/generate-models +category: Getting Started +subCategory: Core +menuOrder: 4 +isDisableFeedbackBlock: true +--- + +In this step, you will generate models using the connected data source from the +last step. Cube's models provide a declarative way to define important facts +about your data, relationships between them and access control. + +## Select tables + +Start by selecting the database tables to use to generate the models, then click +**Generate Schema**: + +
+ Cube's Generate Models Screen showing some tables selected from data source +
+ +After the models have been successfully generated, you should see the following +screen: + +
+ Screen showing successful generation of models +
+ +Click **Build** to continue on the Playground, where you can explore the models +you just created. In the next step, we'll learn more about [how to query +Cube][ref-getting-started-oss-query-cube]. + +[ref-getting-started-oss-query-cube]: /getting-started/core/query-data diff --git a/docs/content/Getting-Started/Core/04-Query-data.mdx b/docs/content/Getting-Started/Core/04-Query-data.mdx new file mode 100644 index 0000000000000..d5d8a99eacb83 --- /dev/null +++ b/docs/content/Getting-Started/Core/04-Query-data.mdx @@ -0,0 +1,102 @@ +--- +title: Query data +permalink: /getting-started/core/query-data +category: Getting Started +subCategory: Core +menuOrder: 6 +isDisableFeedbackBlock: true +--- + +In this step, you will learn how to query your data using the models you created +in the previous step. Cube provides several ways to query your data, and we'll +go over them here. + +## Developer Playground + +The [Developer Playground](/dev-tools/dev-playground) is a web-based tool which +allows for model generation and data exploration. + +Select the measures and dimensions you want to query, and then run the query. +Let's do this for the `Orders` cube you generated in the previous step. + +Click **+ Measure** to display the available measures and add `Orders.count`, +then click **+ Dimension** for available dimensions and add `Orders.status`. + +
+ Cube Cloud Deployment Developer Playground Screen with selected measures and dimensions +
+ +Then click the **Run** button to execute the query and see the results: + +
+ Cube Cloud Deployment Developer Playground Screen showing query results +
+ +## GraphQL API + +Cube supports using GraphQL to query cubes via the `/graphql` endpoint: + +```bash{outputLines: 2-4} +curl \ + --data-raw '{"query":"{cube{orders{count}}}"}' \ + https://localhost:4000/cubejs-api/graphql +``` + +## REST API + +Cube supports using GraphQL to query cubes via the `/load` endpoint: + +```bash{outputLines: 2-4} +curl \ + --data-urlencode 'query={"measures":["Orders.count"]}' \ + https://fierce-boar.aws-eu-central-1.cubecloudapp.dev/dev-mode/dev-hassan-45a93e7e/cubejs-api/v1/load +``` + +## SQL API + +To enable the SQL API, we first need to add a few new environment variables to +the project's `.env` file: + +```bash +CUBEJS_PG_SQL_PORT=5432 +CUBEJS_SQL_USER=myusername +CUBEJS_SQL_PASSWORD=mypassword +``` + +If you're running Cube through Docker Compose, remember to add a port mapping to +the Cube service for `CUBEJS_PG_SQL_PORT`: + +```yaml +services: + cube: + image: cubejs/cube + ports: + - 5432:5432 # Cube SQL API +``` + +Now, you can start your Cube instance and connect via the `psql` client with +provided credentials: + +```bash{outputLines: 2-13} +psql -h 127.0.0.1 --port 5432 -U myusername --password + +psql (14.5, server 14.2 (Cube SQL)) +SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off) +Type "help" for help. + +cube=> SELECT COUNT(*) FROM Orders; + COUNT(UInt8(1)) +----------------- + 10000 +(1 row) +``` diff --git a/docs/content/Getting-Started/Core/05-Add-a-pre-aggregation.mdx b/docs/content/Getting-Started/Core/05-Add-a-pre-aggregation.mdx new file mode 100644 index 0000000000000..10e52981ee8dc --- /dev/null +++ b/docs/content/Getting-Started/Core/05-Add-a-pre-aggregation.mdx @@ -0,0 +1,54 @@ +--- +title: Add a pre-aggregation +permalink: /getting-started/core/add-a-pre-aggregation +category: Getting Started +subCategory: Core +menuOrder: 7 +isDisableFeedbackBlock: true +--- + +In this step, we'll add a pre-aggregation to optimize the performance of a +specific query. Pre-aggregations are a caching technique that massively reduces +query time from seconds to milliseconds, and are extremely useful for speeding +up queries that are run frequently. + +From the Developer Playground, execute a query: + +
+ Cube Developer Playground Screen showing query results +
+ +Just above the results, click on **Query was not accelerated with +pre-aggregation** to bring up the Rollup Designer: + +
+ Cube Developer Playground Screen showing Rollup Designer +
+ +The Rollup Designer will automatically suggest a pre-aggregation for the query; +simply click **Add to the Data Schema** and then retry the query in the +Playground. This time, the query should be accelerated with a pre-aggregation: + +
+ Cube Developer Playground Screen querying a pre-aggregation +
+ +And with that, we conclude our Getting Started with Cube guide. If you'd like to +learn more about Cube, [check out this page][next]. + +[next]: /getting-started/core/learn-more diff --git a/docs/content/Getting-Started/Core/06-Learn-more.mdx b/docs/content/Getting-Started/Core/06-Learn-more.mdx new file mode 100644 index 0000000000000..961064b2ee7d8 --- /dev/null +++ b/docs/content/Getting-Started/Core/06-Learn-more.mdx @@ -0,0 +1,41 @@ +--- +title: Learn more +permalink: /getting-started/core/learn-more +category: Getting Started +subCategory: Core +menuOrder: 8 +isDisableFeedbackBlock: true +--- + +Now that you've set up your first project, learn more about what else Cube can +do for you. + +## Access Control + +Cube uses [JSON Web Tokens](https://jwt.io/) to +[authenticate requests for the HTTP APIs](/security), and +[`checkSqlAuth()`](/config#check-sql-auth) to +[authenticate requests for the SQL API](/backend/sql/security). + +Cube also supports using JWT claims for securing access to data, check out these +[related recipes on the topic](/recipes#recipes-access-control). + +## Modeling + +Learn more about [Cube's data model](/schema/fundamentals/concepts) and how to +effectively model your data for flexible and performant querying. For advanced +users, check out [related recipes](/recipes#recipes-data-schema) for tackling +specific modeling problems. + +## Caching + +Learn more about [Cube's two-level cache](/docs/caching), how +[pre-aggregations can help speed up queries](/caching/pre-aggregations/getting-started) +or for a deeper dive, take a look at the +[related recipes](/recipes#recipes-query-acceleration). + +## Querying + +Cube can be queried in a variety of ways. Learn how to query Cube using +[REST API](/rest-api), [GraphQL API](/backend/graphql), [SQL API](/backend/sql), +or how to [connect using one of our visualization tools](/config/downstream). diff --git a/docs/content/Getting-Started/Getting-Started-Docker-Compose.mdx b/docs/content/Getting-Started/Getting-Started-Docker-Compose.mdx deleted file mode 100644 index 6c16e89ce5aab..0000000000000 --- a/docs/content/Getting-Started/Getting-Started-Docker-Compose.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Docker Compose -permalink: /getting-started/docker/compose ---- - -This guide will help you get Cube running using Docker Compose. - - - -## 1. Create a Docker Compose file - -Create a `docker-compose.yml` file with the following content: - - - -If you're using Linux as the Docker host OS, you'll also need to add -`network_mode: 'host'` to your `docker-compose.yml`. - - - -```yaml -version: '2.2' - -services: - cube: - image: cubejs/cube:latest - ports: - - 4000:4000 - environment: - - CUBEJS_DEV_MODE=true - volumes: - - .:/cube/conf -``` - -## 2. Run Cube - - - -Using Windows? Remember to use [PowerShell][link-powershell] or -[WSL2][link-wsl2] to run the command below. - - - -```bash{promptUser: user} -docker compose up -d -``` - -Check if the container is running: - -```bash{promptUser: user} -docker compose ps -``` - -## 3. Open Developer Playground - -Head to [http://localhost:4000](http://localhost:4000) to open [Developer -Playground][ref-devtools-playground]. - -The [Developer Playground][ref-devtools-playground] has a database connection -wizard that loads when Cube is first started up and no `.env` file is found. -After database credentials have been set up, an `.env` file will automatically -be created and populated with the same credentials. - -
- -
- -Click on the type of database to connect to, and you'll be able to enter -credentials: - -
- -
- -After clicking Apply, you should see tables available to you from the configured -database. Select one to generate a data schema. Once the schema is generated, -you can execute queries on the Build tab. - -## Next Steps - -Generating Data Schema files in the Developer Playground is a good first step to -start modeling your data. You can [learn more about Cube Data -Schema][ref-cubejs-schema] for complex data modeling techniques. - -Learn how to [query Cube with REST API][ref-rest-api] or [use our Javascript -client library and integrations with frontend -frameworks][ref-frontend-introduction]. - -[link-powershell]: - https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.1 -[link-wsl2]: https://docs.microsoft.com/en-us/windows/wsl/install-win10 -[ref-config]: /config -[ref-connecting-to-the-database]: /connecting-to-the-database -[ref-cubejs-schema]: /schema/getting-started -[ref-devtools-playground]: /dev-tools/dev-playground -[ref-env-vars]: /reference/environment-variables -[ref-frontend-introduction]: /frontend-introduction -[ref-rest-api]: /rest-api diff --git a/docs/content/Getting-Started/Getting-Started-Docker.mdx b/docs/content/Getting-Started/Getting-Started-Docker.mdx deleted file mode 100644 index 5e79953826ba8..0000000000000 --- a/docs/content/Getting-Started/Getting-Started-Docker.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Getting Started with Cube using Docker -permalink: /getting-started/docker -redirect_from: - - /getting-started-docker ---- - -This guide will help you get Cube running using Docker. - - - -Prefer using Docker Compose? -[Check out this page instead](/getting-started/docker/compose). - - - - - -## 1. Run Cube with Docker CLI - - - -Using Windows? Remember to use [PowerShell][link-powershell] or -[WSL2][link-wsl2] to run the command below. - - - -In a new folder for your project, run the following command: - -```bash{outputLines: 2-4} -docker run -p 4000:4000 -p 3000:3000 \ - -v ${PWD}:/cube/conf \ - -e CUBEJS_DEV_MODE=true \ - cubejs/cube -``` - -## 2. Open Developer Playground - - - -This step assumes you can connect to a database instance. If you're unable to -connect to a remote instance, please use a Docker image to run one in your local -development environment. - - - -Head to [http://localhost:4000](http://localhost:4000) to open [Developer -Playground][ref-devtools-playground]. - -The [Developer Playground][ref-devtools-playground] has a database connection -wizard that loads when Cube is first started up and no `.env` file is found. -After database credentials have been set up, an `.env` file will automatically -be created and populated with the same credentials. - -
- -
- -Click on the type of database to connect to, and you'll be able to enter -credentials: - -
- -
- -After clicking Apply, you should see tables available to you from the configured -database. Select one to generate a data schema. Once the schema is generated, -you can execute queries on the Build tab. - -## Next Steps - -Generating Data Schema files in the Developer Playground is a good first step to -start modeling your data. You can [learn more about Cube Data -Schema][ref-cubejs-schema] for complex data modeling techniques. - -Learn how to query Cube with [REST API][ref-rest-api], [SQL API][ref-sql-api] or -[use our Javascript client library and integrations with frontend -frameworks][ref-frontend-introduction]. - -[link-powershell]: - https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.1 -[link-wsl2]: https://docs.microsoft.com/en-us/windows/wsl/install-win10 -[ref-config]: /config -[ref-connecting-to-the-database]: /connecting-to-the-database -[ref-cubejs-schema]: /schema/getting-started -[ref-devtools-playground]: /dev-tools/dev-playground -[ref-env-vars]: /reference/environment-variables -[ref-frontend-introduction]: /frontend-introduction -[ref-rest-api]: /rest-api -[ref-sql-api]: /backend/sql diff --git a/docs/content/Getting-Started/Getting-Started-Nodejs.mdx b/docs/content/Getting-Started/Getting-Started-Nodejs.mdx deleted file mode 100644 index 853255e3278b2..0000000000000 --- a/docs/content/Getting-Started/Getting-Started-Nodejs.mdx +++ /dev/null @@ -1,353 +0,0 @@ ---- -title: Getting Started with Cube using Node.js -permalink: /getting-started/nodejs ---- - -This guide walks you through getting started with Cube and requires -[Node.js][link-nodejs] to be installed. - -## 1. Scaffold the project - -Run the following command to get started with Cube, specifying the project name -and optionally your database using the `-d` flag. - -```bash{promptUser: user} -npx cubejs-cli create -d -``` - -You can find [all available databases here][ref-connecting-to-the-database]. For -example, to create a new project with the Postgres database, use the following: - -```bash{promptUser: user} -npx cubejs-cli create hello-world -d postgres -``` - -Once run, the `create` command will create a new project directory that contains -the scaffolding for your new Cube project. This includes all the files necessary -to spin up the Cube backend and some example schema files to highlight the -format of the Cube Data Schema layer. - -The `.env` file in this project directory contains placeholders for the relevant -database credentials. Setting credentials is covered in the [Connecting to the -Database][ref-connecting-to-the-database] section. - -## 2. Define Your Data Schema - -Cube uses [Data Schema][ref-cubejs-schema] to generate and execute SQL. - -It acts as an ORM for your database and it is flexible enough to model -everything from simple counts to cohort retention and funnel analysis. [Read -more about Cube Schema][ref-cubejs-schema]. - -You can generate schema files using [Developer Playground][ref-dev-playground]. -To do so, you can start the dev server from project directory like this: - -```bash{promptUser: user} -npm run dev -``` - -Then go to `http://localhost:4000` and use Developer Playground to generate -schema files. - -### <--{"id" : "2. Define Your Data Schema"}--> Manually creating Data Schema files - -You can also add schema files to the `schema` folder manually: - -```javascript -// schema/users.js - -cube(`Users`, { - measures: { - count: { - type: `count`, - }, - }, - - dimensions: { - age: { - type: `number`, - sql: `age`, - }, - - createdAt: { - type: `time`, - sql: `createdAt`, - }, - - country: { - type: `string`, - sql: `country`, - }, - }, -}); -``` - -## 3. Visualize Results - -The Cube client provides set of methods to access Cube API and to work with -query result. The client itself doesn't provide any visualizations and is -designed to work with existing chart libraries. You can find more information -about [the Cube client as well as our frontend integrations -here][ref-frontend-intro]. - -As a shortcut you can run your dev server first: - -```bash{promptUser: user} -npm run dev -``` - -Then open `http://localhost:4000` in a browser to see visualization examples. -This will open a Developer Playground app. You can change the metrics and -dimensions of the example to use the schema you defined earlier, change the -chart types, generate sample code and more! - -Cube also provides a [REST API](/rest-api) for accessing your data -programmatically. - -### <--{"id" : "3. Visualize Results"}--> Cube Client Installation - -Vanilla JS: - -```bash{promptUser: user} -npm i --save @cubejs-client/core -``` - -React: - -```bash{promptUser: user} -npm i --save @cubejs-client/core -npm i --save @cubejs-client/react -``` - -Vue: - -```bash{promptUser: user} -npm i --save @cubejs-client/core -npm i --save @cubejs-client/vue -``` - -Angular: - -```bash{promptUser: user} -npm i --save @cubejs-client/core -npm i --save @cubejs-client/ngx -``` - -### <--{"id" : "3. Visualize Results"}--> Example Usage - -#### Vanilla Javascript - -Instantiate the Cube API and then use it to fetch data. `CubejsApi.load()` -accepts a query, which is a plain Javascript object. -[Learn more about the query format here](query-format). - -```javascript -import cubejs from '@cubejs-client/core'; -import Chart from 'chart.js'; -import chartjsConfig from './toChartjsData'; - -const cubejsApi = cubejs('YOUR-CUBEJS-API-TOKEN', { - apiUrl: 'http://localhost:4000/cubejs-api/v1', -}); - -const resultSet = await cubejsApi.load({ - measures: ['Stories.count'], - timeDimensions: [ - { - dimension: 'Stories.time', - dateRange: ['2015-01-01', '2015-12-31'], - granularity: 'month', - }, - ], -}); -const context = document.getElementById('myChart'); -new Chart(context, chartjsConfig(resultSet)); -``` - -#### React - -Import `cubejs` and `QueryRenderer` components, and use them to fetch the data. -In the example below, we use `recharts` to visualize data. - -```jsx -import React from 'react'; -import { LineChart, Line, XAxis, YAxis } from 'recharts'; -import cubejs from '@cubejs-client/core'; -import { QueryRenderer } from '@cubejs-client/react'; - -const cubejsApi = cubejs('YOUR-CUBEJS-API-TOKEN', { - apiUrl: 'http://localhost:4000/cubejs-api/v1', -}); - -export default () => { - return ( - { - if (!resultSet) { - return 'Loading...'; - } - - return ( - - - - - - ); - }} - /> - ); -}; -``` - -#### Vue - -Import `cubejs` and `QueryRenderer` components, and use them to fetch the data. -In the example below, we use `vue-chartkick` to visualize data. - -```javascript - - - -``` - -#### Angular - -Add CubejsClientModule to your `app.module.ts` file: - -```typescript -import { CubejsClientModule } from '@cubejs-client/ngx'; -import { environment } from '../../environments/environment'; - -const cubejsOptions = { - token: environment.CUBEJS_API_TOKEN, - options: { apiUrl: environment.CUBEJS_API_URL } -}; - -@NgModule({ - declarations: [ - ... - ], - imports: [ - ..., - CubejsClientModule.forRoot(cubejsOptions) - ], - providers: [...], - bootstrap: [...] -}) -export class AppModule { } -``` - -Then you can inject `CubejsClient` into your components or services: - -```typescript -import { CubejsClient } from '@cubejs-client/ngx'; - -export class AppComponent { - constructor(private cubejs: CubejsClient) {} - - ngOnInit() { - this.cubejs - .load({ - measures: ['some_measure'], - }) - .subscribe( - (resultSet) => { - this.data = resultSet.chartPivot(); - }, - (err) => console.log('HTTP Error', err) - ); - } -} -``` - -## 4. Deploy to Production - -Cube has first-class deployment support for [Docker][link-docker]: - -```bash{outputLines: 2-12} -docker run --rm \ - --name cubejs-docker-demo \ - -e CUBEJS_API_SECRET= \ - -e CUBEJS_DB_HOST= \ - -e CUBEJS_DB_NAME= \ - -e CUBEJS_DB_USER= \ - -e CUBEJS_DB_PASS= \ - -e CUBEJS_DB_TYPE=postgres \ - --volume "$(pwd):/cube/conf" \ - /cubejs-docker-demo -``` - -For more information on deploying our official Docker image, please consult the -[Deployment Guide][ref-docker-deployment-guide]. - -[link-docker]: https://www.docker.com/ -[link-nodejs]: https://nodejs.org/en/ -[ref-dev-playground]: /dev-tools/dev-playground -[ref-frontend-intro]: /frontend-introduction -[ref-docker-deployment-guide]: /deployment/platforms/docker -[ref-connecting-to-the-database]: /connecting-to-the-database -[ref-cubejs-schema]: /schema/getting-started diff --git a/docs/content/Getting-Started/Overview.mdx b/docs/content/Getting-Started/Overview.mdx index 44ade2950fda7..d5dfed33a8549 100644 --- a/docs/content/Getting-Started/Overview.mdx +++ b/docs/content/Getting-Started/Overview.mdx @@ -1,29 +1,31 @@ --- -title: Getting Started +title: Overview permalink: /getting-started category: Getting Started menuOrder: 1 isDisableFeedbackBlock: true --- -You can get started with Cube locally or self-host it with Docker. +You can get started with Cube in one of two ways. The first is to use [Cube +Cloud][cube-cloud], our managed platform for Cube that includes features such as +collaboration for teams, a web-based IDE, automatic scaling and observability +features for instrumenting queries. Cube Cloud also comes with a free tier for +development projects and proof-of-concepts. -Alternatively, you can get started with [Cube Cloud](https://cube.dev/cloud/). -It provides managed experience for Cube and has a free tier for development -projects and proofs of concept. +The second option is to run Cube on your own infrastructure. - + - + -There's also a legacy option to get started with -[Node.js](getting-started/nodejs). +[cube-cloud]: https://cube.dev/cloud/ +[docker-cube]: https://hub.docker.com/r/cubejs/cube diff --git a/docs/content/SQL-API/Getting-Started.mdx b/docs/content/SQL-API/Getting-Started.mdx deleted file mode 100644 index af949f8a21717..0000000000000 --- a/docs/content/SQL-API/Getting-Started.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Getting Started -category: SQL API -permalink: /backend/sql/getting-started -menuOrder: 2 ---- - -## Cube Cloud - -The first step to get started with the SQL API in Cube Cloud is to create a -deployment. You can follow this -[step-by-step guide on creating a deployment within Cube Cloud](/cloud/getting-started/create). - -Once the deployment is ready, click **How to connect** link on the Overview -page. It will open a modal with instructions on different ways to connect to -Cube. Navigate to the SQL API tab and enable the SQL API. - -Once it is enabled, you should see a screen like the one below with your -connection credentials. - -
- -
- -Since the Cube SQL API is Postgres-compatible, please make sure to select -**Postgres** as a database type when connecting from BI tools. - -## Self-hosted Cube - -To enable the SQL API, we first need to add a new environment variable: - -```dotenv -CUBEJS_PG_SQL_PORT=5432 -``` - -If you're running Cube through Docker Compose, remember to add a port mapping to -the Cube service for `CUBEJS_PG_SQL_PORT`: - -```yaml -services: - cube: - image: cubejs/cube - ports: - - 5432:5432 # Cube SQL API -``` - -Or if running Docker from command line: - -```bash{outputLines: 2-10} -docker run -p 4000:4000 -p 5432:5432 \ - -v ${PWD}:/cube/conf \ - -e CUBEJS_DEV_MODE=true \ - -e CUBEJS_PG_SQL_PORT=5432 \ - cubejs/cube -``` - -Then, set Cube SQL credentials auth: - -```dotenv -CUBEJS_SQL_USER=myusername -CUBEJS_SQL_PASSWORD=mypassword -``` - -Now, you can start your Cube instance and connect via the `psql` client with -provided credentials: - -```bash{promptUser: user} -psql -h 127.0.0.1 --port 5432 -U myusername --password -``` diff --git a/docs/content/Schema/Getting-Started.mdx b/docs/content/Schema/Getting-Started.mdx deleted file mode 100644 index 0f4694de717a3..0000000000000 --- a/docs/content/Schema/Getting-Started.mdx +++ /dev/null @@ -1,293 +0,0 @@ ---- -title: Getting Started with Data Modeling -menuTitle: Getting Started -permalink: /schema/getting-started -category: Reference -menuOrder: 1 -proofread: 06/18/2019 -redirect_from: - - /getting-started-cubejs-schema ---- - - - We're excited to expand the beta of YAML and Python support in Cube data modeling.
- Please reach out to us if you’d like to sign up for early access. - - -A Cube Data Schema is used to model raw data into meaningful business -definitions and pre-aggregate data for optimal results. The data schema is -exposed through the [querying API][ref-backend-restapi] that allows end-users to -query a wide variety of analytical queries without modifying the schema itself. - -Let’s use a users table with the following columns as an example: - -| id | paying | city | company_name | -| --- | ------ | ------------- | ------------ | -| 1 | true | San Francisco | Pied Piper | -| 2 | true | Palo Alto | Raviga | -| 3 | true | Redwood | Aviato | -| 4 | false | Mountain View | Bream-Hall | -| 5 | false | Santa Cruz | Hooli | - -We can start with a set of simple questions about users we want to answer: - -- How many users do we have? -- How many paying users? -- What is the percentage of paying users out of the total? -- How many users, paying or not, are from different cities and companies? - -We don’t need to write SQL queries for every question, since the data schema -allows building well-organized and reusable SQL. - -## 1. Creating a Cube - -In Cube, [cubes][ref-schema-cube] are used to organize entities and -connections between entities. Usually one cube is created for each table in the -database, such as `users`, `orders`, `products`, etc. In the `sql` parameter of -the cube we define a base table for this cube. In our case, the base table is -simply our `users` table. - - - -```javascript -cube(`Users`, { - sql: `SELECT * FROM users`, -}); -``` - -```yaml -cubes: - - name: Users - sql: SELECT * FROM users -``` - - - -## 2. Adding Measures and Dimensions - -Once the base table is defined, the next step is to add -[measures][ref-schema-measures] and [dimensions][ref-schema-dimensions] to the -cube. - - - -**Measures** are referred to as quantitative data, such as number of units sold, -number of unique visits, profit, and so on. - -**Dimensions** are referred to as categorical data, such as state, gender, -product name, or units of time (e.g., day, week, month). - - - -Let's go ahead and create our first measure and two dimensions: - - - -```javascript -cube(`Users`, { - sql: `SELECT * FROM users`, - - measures: { - count: { - sql: `id`, - type: `count`, - }, - }, - - dimensions: { - city: { - sql: `city`, - type: `string`, - }, - - company_name: { - sql: `company_name`, - type: `string`, - }, - }, -}); -``` - -```yaml -cubes: - - name: Users - sql: SELECT * FROM users - measures: - - name: count - sql: id - type: count - dimensions: - - name: city - sql: city - type: string - - name: company_name - sql: company_name - type: string -``` - - - -Let's break down the above code snippet piece-by-piece. After defining the base -table for the cube (with the `sql` property), we create a `count` measure in the -`measures` block. [The type][ref-schema-types-formats] `count` and sql `id` -means that when this measure will be requested via an API, Cube will generate -and execute the following SQL: - -```sql -SELECT count(id) from users; -``` - -When we apply a city dimension to the measure to see "Where are users based?", -Cube will generate SQL with a `GROUP BY` clause: - -```sql -SELECT city, count(id) from users GROUP BY 1; -``` - -You can add as many dimensions as you want to your query when you perform -grouping. - -## 3. Adding Filters to Measures - -Now let's answer the next question – "How many paying users do we have?". To -accomplish this, we will introduce **measure filters**: - - - -```javascript -cube(`Users`, { - measures: { - count: { - sql: `id`, - type: `count`, - }, - - paying_count: { - sql: `id`, - type: `count`, - filters: [{ sql: `${CUBE}.paying = 'true'` }], - }, - }, -}); -``` - -```yaml -cubes: - - name: Users - measures: - - name: count - sql: id - type: count - - name: paying_count - sql: id - type: count - filters: - - sql: "{CUBE}.paying = 'true'" -``` - - - - - -It is best practice to prefix references to table columns with the name of the -cube or with the `CUBE` constant when referencing the current cube's column. - - - -That's it! Now we have the `paying_count` measure, which shows only our paying -users. When this measure is requested, Cube will generate the following SQL: - -```sql -SELECT - count( - CASE WHEN (users.paying = 'true') THEN users.id END - ) "users.paying_count" -FROM users -``` - -Since the `filters` property is an array, you can apply as many filters as -required. `paying_count` can be used with dimensions the same way as a simple -`count`. We can group `paying_count` by `city` and `companyName` simply by adding -these dimensions alongside measures in the requested query. - -## 4. Using Calculated Measures - -To answer "What is the percentage of paying users out of the total?", we need to -calculate the paying users ratio, which is basically `paying_count / count`. -Cube makes it extremely easy to perform this kind of calculation. Let's add a -new measure to our cube called `paying_percentage`: - - - -```javascript -cube(`Users`, { - measures: { - count: { - sql: `id`, - type: `count`, - }, - - paying_count: { - sql: `id`, - type: `count`, - filters: [{ sql: `${CUBE}.paying = 'true'` }], - }, - - paying_percentage: { - sql: `100.0 * ${paying_count} / ${count}`, - type: `number`, - format: `percent`, - }, - }, -}); -``` - -```yaml -cubes: - - name: Users - measures: - - name: count - sql: id - type: count - - name: paying_count - sql: id - type: count - filters: - - sql: "{CUBE}.paying = 'true'" - - name: paying_percentage - sql: "100.0 * {paying_count} / {count}" - type: number - format: percent -``` - - - -Here we defined a calculated measure `paying_percentage`, which divides -`paying_count` by `count`. This example shows how you can reference measures -inside other measure definitions. When you request the `paying_percentage` -measure via an API, the following SQL will be generated: - -```sql -SELECT - 100.0 * count( - CASE WHEN (users.paying = 'true') THEN users.id END - ) / count(users.id) "users.paying_percentage" -FROM users -``` - -As with other measures, `paying_percentage` can be used with dimensions. - -## 5. Next Steps - -1. [Examples][ref-examples] -2. [Query format][ref-backend-query-format] -3. [REST API][ref-backend-restapi] -4. [Schema reference documentation][ref-schema-cube] - -[ref-backend-restapi]: /rest-api -[ref-schema-cube]: /schema/reference/cube -[ref-schema-measures]: /schema/reference/measures -[ref-schema-dimensions]: /schema/reference/dimensions -[ref-schema-types-formats]: /schema/reference/types-and-formats -[ref-examples]: /examples -[ref-backend-query-format]: /query-format From 76f970b09213817336faa34e7b2a87c688ce2b2b Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Thu, 30 Mar 2023 12:33:46 +0200 Subject: [PATCH 02/13] Rewrite Overview --- docs/content/Getting-Started/Overview.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/content/Getting-Started/Overview.mdx b/docs/content/Getting-Started/Overview.mdx index d5dfed33a8549..c044162567885 100644 --- a/docs/content/Getting-Started/Overview.mdx +++ b/docs/content/Getting-Started/Overview.mdx @@ -6,13 +6,15 @@ menuOrder: 1 isDisableFeedbackBlock: true --- -You can get started with Cube in one of two ways. The first is to use [Cube -Cloud][cube-cloud], our managed platform for Cube that includes features such as -collaboration for teams, a web-based IDE, automatic scaling and observability -features for instrumenting queries. Cube Cloud also comes with a free tier for -development projects and proof-of-concepts. +You can get started with Cube in one of two ways. -The second option is to run Cube on your own infrastructure. +We recommend using [Cube Cloud][cube-cloud], our managed platform for Cube, +because it's the easiest way to build, test, deploy, and manage Cube projects. +Cube Cloud includes features such as collaboration for teams, a web-based IDE, +auto-scaling, and observability. Cube Cloud also comes with a free tier for +development and proof-of-concept projects. + +Alternatively, you can run Cube on your own infrastructure. [cube-cloud]: https://cube.dev/cloud/ -[docker-cube]: https://hub.docker.com/r/cubejs/cube From 4cc947db146f11e60fbd61ed51f9eba7fe8f0300 Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Thu, 30 Mar 2023 13:55:07 +0200 Subject: [PATCH 03/13] Rewrite Overviews --- docs/content/Getting-Started/Cloud/01-Overview.mdx | 8 ++++---- docs/content/Getting-Started/Core/01-Overview.mdx | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/content/Getting-Started/Cloud/01-Overview.mdx b/docs/content/Getting-Started/Cloud/01-Overview.mdx index eee3b53ee56c4..cf79dc49445fc 100644 --- a/docs/content/Getting-Started/Cloud/01-Overview.mdx +++ b/docs/content/Getting-Started/Cloud/01-Overview.mdx @@ -8,15 +8,15 @@ isDisableFeedbackBlock: true --- To get started with Cube Cloud, first we'll create a new deployment, connect it -to a database and generate models from it. Then we'll query Cube using the +to a database, and generate a data model from it. Then, we'll run queries using the Developer Playground and APIs. Finally, we'll add a pre-aggregation to optimize query latency down to milliseconds. -This guide will walk you through each task: +This guide will walk you through the following tasks: - [Create a new deployment](/getting-started/cloud/create-a-deployment) -- [Generate models from a connected data source](/getting-started/cloud/generate-models) -- [Query Cube using the Developer Playground and APIs](/getting-started/cloud/query-data) +- [Generate a data model from a connected data source](/getting-started/cloud/generate-models) +- [Run queries using the Developer Playground and APIs](/getting-started/cloud/query-data) - [Add a pre-aggregation to optimize query performance](/getting-started/cloud/add-a-pre-aggregation) If you'd prefer to run Cube locally, then you can refer to [Getting Started diff --git a/docs/content/Getting-Started/Core/01-Overview.mdx b/docs/content/Getting-Started/Core/01-Overview.mdx index 5f2eab620e2cd..7298b71f3b7cf 100644 --- a/docs/content/Getting-Started/Core/01-Overview.mdx +++ b/docs/content/Getting-Started/Core/01-Overview.mdx @@ -2,21 +2,21 @@ title: Overview permalink: /getting-started/core/overview category: Getting Started -subCategory: Core +subCategory: Cube Core menuOrder: 3 isDisableFeedbackBlock: true --- -To get started with Cube Cloud, first we'll create a new deployment, connect it -to a database and generate models from it. Then we'll query Cube using the +To get started with Cube Core, first we'll create a new project, connect it +to a database and generate a data model from it. Then, we'll run queries using the Developer Playground and APIs. Finally, we'll add a pre-aggregation to optimize query latency down to milliseconds. This guide will walk you through the following tasks: - [Create a new project](/getting-started/core/create-a-project) -- [Generate models from a connected data source](/getting-started/core/generate-models) -- [Query Cube using the Developer Playground and APIs](/getting-started/core/query-data) +- [Generate a data model from a connected data source](/getting-started/core/generate-models) +- [Run queries using the Developer Playground and APIs](/getting-started/core/query-data) - [Add a pre-aggregation to optimize query performance](/getting-started/core/add-a-pre-aggregation) If you'd prefer to try Cube Cloud, then you can refer to [Getting Started using From 60dd38c7dd43b17ebfc24b1ead51533333d3f16b Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Thu, 30 Mar 2023 14:00:13 +0200 Subject: [PATCH 04/13] Rewrite Overviews, once again --- docs/content/Getting-Started/Cloud/01-Overview.mdx | 10 +++++----- docs/content/Getting-Started/Core/01-Overview.mdx | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/content/Getting-Started/Cloud/01-Overview.mdx b/docs/content/Getting-Started/Cloud/01-Overview.mdx index cf79dc49445fc..0a7333159894a 100644 --- a/docs/content/Getting-Started/Cloud/01-Overview.mdx +++ b/docs/content/Getting-Started/Cloud/01-Overview.mdx @@ -1,5 +1,5 @@ --- -title: Overview +title: Getting started with Cube Cloud permalink: /getting-started/cloud/overview category: Getting Started subCategory: Cube Cloud @@ -7,10 +7,10 @@ menuOrder: 2 isDisableFeedbackBlock: true --- -To get started with Cube Cloud, first we'll create a new deployment, connect it -to a database, and generate a data model from it. Then, we'll run queries using the -Developer Playground and APIs. Finally, we'll add a pre-aggregation to optimize -query latency down to milliseconds. +First, we'll create a new deployment, connect it to a database, and generate a +data model from it. Then, we'll run queries using the Developer Playground and +APIs. Finally, we'll add a pre-aggregation to optimize query latency down to +milliseconds. This guide will walk you through the following tasks: diff --git a/docs/content/Getting-Started/Core/01-Overview.mdx b/docs/content/Getting-Started/Core/01-Overview.mdx index 7298b71f3b7cf..275bae7e685b7 100644 --- a/docs/content/Getting-Started/Core/01-Overview.mdx +++ b/docs/content/Getting-Started/Core/01-Overview.mdx @@ -1,5 +1,5 @@ --- -title: Overview +title: Getting started with Cube Core permalink: /getting-started/core/overview category: Getting Started subCategory: Cube Core @@ -7,10 +7,10 @@ menuOrder: 3 isDisableFeedbackBlock: true --- -To get started with Cube Core, first we'll create a new project, connect it -to a database and generate a data model from it. Then, we'll run queries using the -Developer Playground and APIs. Finally, we'll add a pre-aggregation to optimize -query latency down to milliseconds. +First, we'll create a new project, connect it to a database and generate a data +model from it. Then, we'll run queries using the Developer Playground and APIs. +Finally, we'll add a pre-aggregation to optimize query latency down to +milliseconds. This guide will walk you through the following tasks: From 74244813498095863214760b1c24553b6326f08f Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Thu, 30 Mar 2023 14:56:35 +0200 Subject: [PATCH 05/13] Add Btn (inline button) --- docs/src/components/InlineButton/InlineButton.tsx | 12 ++++++++++++ docs/src/components/InlineButton/styles.module.scss | 13 +++++++++++++ docs/src/templates/DocTemplate.tsx | 2 ++ docs/static/styles/variables.scss | 1 + 4 files changed, 28 insertions(+) create mode 100644 docs/src/components/InlineButton/InlineButton.tsx create mode 100644 docs/src/components/InlineButton/styles.module.scss diff --git a/docs/src/components/InlineButton/InlineButton.tsx b/docs/src/components/InlineButton/InlineButton.tsx new file mode 100644 index 0000000000000..204e051e05fc1 --- /dev/null +++ b/docs/src/components/InlineButton/InlineButton.tsx @@ -0,0 +1,12 @@ +import React from 'react'; +import * as styles from './styles.module.scss'; + +export type InlineButtonProps = { + children: string; +} + +export const InlineButton = ({ children }: InlineButtonProps) => { + return {children}; +}; + +export default InlineButton; \ No newline at end of file diff --git a/docs/src/components/InlineButton/styles.module.scss b/docs/src/components/InlineButton/styles.module.scss new file mode 100644 index 0000000000000..9d08b0c127aa5 --- /dev/null +++ b/docs/src/components/InlineButton/styles.module.scss @@ -0,0 +1,13 @@ +@import "../../../static/styles/variables.scss"; + +.button { + display: inline-block; + padding: 0 6px; + background: $white; + border: 1px solid $dark-05; + box-shadow: 2px 2px 0px $dark-05; + border-radius: 4px; + font-size: 17px; + line-height: 24px; + margin-right: 2px; +} \ No newline at end of file diff --git a/docs/src/templates/DocTemplate.tsx b/docs/src/templates/DocTemplate.tsx index dfdf0b2ab7832..47c9c3d63a536 100644 --- a/docs/src/templates/DocTemplate.tsx +++ b/docs/src/templates/DocTemplate.tsx @@ -45,6 +45,7 @@ import MyH3 from '../components/Headers/MyH3'; import { ParameterTable } from '../components/ReferenceDocs/ParameterTable'; import { Snippet, SnippetGroup } from '../components/Snippets/SnippetGroup'; import { CodeTabs } from '../components/CodeTabs'; +import InlineButton from '../components/InlineButton/InlineButton'; const MyH4: React.FC<{ children: string }> = ({ children }) => { return (

{children}

); @@ -68,6 +69,7 @@ const components = { h3: ScrollSpyH3, h4: MyH4, CodeTabs, + Btn: InlineButton, }; const MDX = (props) => ( diff --git a/docs/static/styles/variables.scss b/docs/static/styles/variables.scss index 471e908e57731..cc2d9cc8c851e 100644 --- a/docs/static/styles/variables.scss +++ b/docs/static/styles/variables.scss @@ -4,6 +4,7 @@ $purple-04: #CAC9FF; $purple-text: #665DE8; $dark-01: #141446; $dark-04: #A1A1B5; +$dark-05: #E5E5EC; $pink: #FF6492; $pink-02: #FF83A8; $pink-04: #FFC1D3; From cd53533ca5470fa757d60318d7cd7e399d14d335 Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Thu, 30 Mar 2023 14:56:55 +0200 Subject: [PATCH 06/13] Make images span full width --- docs/static/styles/_layout.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/static/styles/_layout.scss b/docs/static/styles/_layout.scss index 2ffe4fb4c7ecb..c3a188fb579b4 100644 --- a/docs/static/styles/_layout.scss +++ b/docs/static/styles/_layout.scss @@ -87,7 +87,7 @@ a { img:not(.mainTabImg) { border: 1px solid #ECECF0; border-radius: 4px; - max-width: 100%; + width: 100%; margin: 24px 0; box-shadow: none !important; } From 8a3ad7f45e505ca7754dd02c536182afc42f0abf Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Thu, 30 Mar 2023 16:00:24 +0200 Subject: [PATCH 07/13] Edit Cloud pages --- .../Cloud/02-Create-a-deployment.mdx | 62 +++++++++---------- .../Cloud/03-Generate-models.mdx | 33 +++++----- .../Getting-Started/Cloud/04-Query-data.mdx | 45 +++++++------- .../Cloud/05-Add-a-pre-aggregation.mdx | 16 +++-- .../Getting-Started/Cloud/06-Learn-more.mdx | 35 +++++------ 5 files changed, 97 insertions(+), 94 deletions(-) diff --git a/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx index 830b19967b0d6..a3f0b3110aed7 100644 --- a/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx +++ b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx @@ -7,22 +7,19 @@ menuOrder: 3 isDisableFeedbackBlock: true --- - +In this step, we will create a new deployment in Cube Cloud. A deployment +represents a data model, configuration, and managed infrastructure. We will use +it to connect a data source and generate data models. + +## Create an account To continue with this guide, you'll need to have a Cube Cloud account. If you don't have one yet, [click here to sign up][cube-cloud-signup] for free. - - -In this step, we will create a new deployment in Cube Cloud. Deployments -represent a project, and we will use it to connect our data source and generate -models. - -## Create deployment +## Create a deployment -The first step in creating a deployment is to [sign in to your Cube Cloud -account][cube-cloud-signin]. After signing in, click the **Create Deployment** -button: +First, [sign in to your Cube Cloud account][cube-cloud-signin]. Then, +click Create Deployment:
-Give the deployment a name and select the cloud provider and region of your -choice and click **Next**: +Give the deployment a name, select the cloud provider and region of your choice, +and click Next:
-## Set up Cube project +## Set up a Cube project -Next, click **Create** to create a new project from scratch: +Next, click Create to create a new project from scratch:
+ Cube Cloud Setup Database Screen +
-Want to use a sample database instead? Use the credentials below: +Want to use a sample database instead? Select PostgreSQL and use the +credentials below:
@@ -79,20 +86,9 @@ Want to use a sample database instead? Use the credentials below: -To do this, first select **PostgreSQL** as the data source: - -
- Cube Cloud Setup Database Screen -
- -After selecting the data source, enter valid credentials for it and click -**Apply**. Check the [Connecting to Databases][ref-conf-db] page for more -details on specific data sources. +After selecting the data source, enter valid credentials for it and +click Apply. Check the [Connecting to Databases][ref-conf-db] +page for more details on specific data sources.
Measures and Dimensions:
Primary Keys to progress to the next step:
Joins to +move to the next step:
Review:
YAML (recommended) or JavaScript format and +click Confirm & Generate:
-You're now ready for the last step, [querying the data source via the Cube -API][ref-getting-started-cloud-query-cube]. +You're now ready for the last step, [querying the +data][ref-getting-started-cloud-query-cube]. [ref-getting-started-cloud-query-cube]: /getting-started/cloud/query-data diff --git a/docs/content/Getting-Started/Cloud/04-Query-data.mdx b/docs/content/Getting-Started/Cloud/04-Query-data.mdx index 4fd5d61608181..f0f6b254baa0a 100644 --- a/docs/content/Getting-Started/Cloud/04-Query-data.mdx +++ b/docs/content/Getting-Started/Cloud/04-Query-data.mdx @@ -7,17 +7,17 @@ menuOrder: 5 isDisableFeedbackBlock: true --- -In this step, you will learn how to query your data using the models you created -in the previous step. Cube Cloud provides several ways to query your data, and -we'll go over them here. +In this step, you will learn how to query your data using the data models you +created in the previous step. Cube Cloud provides several ways to query your +data, and we'll go over them here. ## Developer Playground -The Playground is a web-based tool that allows you to query your data without -writing any code. It's a great way to get started with Cube and explore your -data. +The Developer Playground is a web-based tool that allows you to query your data +without connecting any tools or writing any code. It's a fastest way to explore +your data. -To open the Playground, open the **Playground** page in Cube Cloud: +Navigate to the Playground page in Cube Cloud:
+ Measure to display the available measures and add +`Orders.count`, then click Run:
-Next, click **+ Dimension** for available dimensions and add `Orders.status` and -then click **Run** again: +Next, click + Dimension for available dimensions, add +`Orders.status`, and then click Run again:
-To see an example of how to query the GraphQL API using cURL, click **How to -connect your application**: +To see an example of how to query the GraphQL API using `curl`, click How +to connect your application:
-To see an example of how to query the REST API using cURL, click **How to -connect your application**: +To see an example of how to query the REST API using `curl`, click How to +connect your application:
Settings page and enable the SQL API. -Once it is enabled, you should see a screen like the one below with your -connection credentials: +Then, on the Overview page, click How to connect, which +will open instructions on connecting different tools to the SQL API. You should +see a screen with your connection credentials:
SELECT COUNT(*) FROM Orders; ``` Since the Cube SQL API is Postgres-compatible, please make sure to select -**Postgres** as the database type when connecting from BI tools. +Postgres as the database type when connecting from BI tools. -Now that we've seen how to query Cube across its APIs, let's take a look at [how -to add pre-aggregations to your deployment to speed up your queries][next]. +Now that we've seen how to use Cube's APIs, let's take a look at [how to add +pre-aggregations][next] to speed up your queries. [next]: /getting-started/cloud/add-a-pre-aggregation diff --git a/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx b/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx index 432d67ccf06ef..437813f23eb5c 100644 --- a/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx +++ b/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx @@ -9,10 +9,10 @@ isDisableFeedbackBlock: true In this step, we'll add a pre-aggregation to optimize the performance of a specific query. Pre-aggregations are a caching technique that massively reduces -query time from seconds to milliseconds, and are extremely useful for speeding +query time from seconds to milliseconds. They are extremely useful for speeding up queries that are run frequently. -From the Developer Playground, execute a query: +From the Developer Playground page, execute a query:
-Just above the results, click on **Query was not accelerated with -pre-aggregation** to bring up the Rollup Designer: +Just above the results, click on Query was not accelerated with +pre-aggregation to bring up the Rollup Designer:
The Rollup Designer will automatically suggest a pre-aggregation for the query; -simply click **Add to the Data Schema** and then retry the query in the -Playground. This time, the query should be accelerated with a pre-aggregation: +click Add to the Data Schema and then retry the query in the +Playground. This time, the query should be accelerated with a pre-aggregation. + +It takes a bit of time to build a pre-aggregation, so the first run might not +necessarily fast. Click Rerun query a few times until you see a +subsecond query time.
Date: Thu, 30 Mar 2023 18:21:34 +0200 Subject: [PATCH 08/13] Edit Core pages --- .../Cloud/03-Generate-models.mdx | 2 +- .../Getting-Started/Cloud/04-Query-data.mdx | 4 +- .../Getting-Started/Core/01-Overview.mdx | 2 +- .../Core/02-Create-a-project.mdx | 76 ++++++++++++------- .../Core/03-Generate-models.mdx | 44 ----------- .../{04-Query-data.mdx => 03-Query-data.mdx} | 49 +++++++----- ...ation.mdx => 04-Add-a-pre-aggregation.mdx} | 14 ++-- .../Getting-Started/Core/05-Learn-more.mdx | 41 ++++++++++ .../Getting-Started/Core/06-Learn-more.mdx | 41 ---------- 9 files changed, 131 insertions(+), 142 deletions(-) delete mode 100644 docs/content/Getting-Started/Core/03-Generate-models.mdx rename docs/content/Getting-Started/Core/{04-Query-data.mdx => 03-Query-data.mdx} (54%) rename docs/content/Getting-Started/Core/{05-Add-a-pre-aggregation.mdx => 04-Add-a-pre-aggregation.mdx} (78%) create mode 100644 docs/content/Getting-Started/Core/05-Learn-more.mdx delete mode 100644 docs/content/Getting-Started/Core/06-Learn-more.mdx diff --git a/docs/content/Getting-Started/Cloud/03-Generate-models.mdx b/docs/content/Getting-Started/Cloud/03-Generate-models.mdx index ade4682c45399..5af9817b77ed5 100644 --- a/docs/content/Getting-Started/Cloud/03-Generate-models.mdx +++ b/docs/content/Getting-Started/Cloud/03-Generate-models.mdx @@ -99,7 +99,7 @@ a few moments you should see the following screen: />
-You're now ready for the last step, [querying the +You're now ready for the next step, [querying the data][ref-getting-started-cloud-query-cube]. [ref-getting-started-cloud-query-cube]: /getting-started/cloud/query-data diff --git a/docs/content/Getting-Started/Cloud/04-Query-data.mdx b/docs/content/Getting-Started/Cloud/04-Query-data.mdx index f0f6b254baa0a..1bd5de469d420 100644 --- a/docs/content/Getting-Started/Cloud/04-Query-data.mdx +++ b/docs/content/Getting-Started/Cloud/04-Query-data.mdx @@ -140,10 +140,10 @@ fierce-bear=> SELECT COUNT(*) FROM Orders; (1 row) ``` -Since the Cube SQL API is Postgres-compatible, please make sure to select -Postgres as the database type when connecting from BI tools. +Since the SQL API is Postgres-compatible, please make sure to select Postgres as the database type when [connecting from BI tools][ref-downstream]. Now that we've seen how to use Cube's APIs, let's take a look at [how to add pre-aggregations][next] to speed up your queries. +[ref-downstream]: /config/downstream [next]: /getting-started/cloud/add-a-pre-aggregation diff --git a/docs/content/Getting-Started/Core/01-Overview.mdx b/docs/content/Getting-Started/Core/01-Overview.mdx index 275bae7e685b7..077a9cf6f922e 100644 --- a/docs/content/Getting-Started/Core/01-Overview.mdx +++ b/docs/content/Getting-Started/Core/01-Overview.mdx @@ -3,7 +3,7 @@ title: Getting started with Cube Core permalink: /getting-started/core/overview category: Getting Started subCategory: Cube Core -menuOrder: 3 +menuOrder: 2 isDisableFeedbackBlock: true --- diff --git a/docs/content/Getting-Started/Core/02-Create-a-project.mdx b/docs/content/Getting-Started/Core/02-Create-a-project.mdx index 6e270e7fdcab3..9cc4ee34a986d 100644 --- a/docs/content/Getting-Started/Core/02-Create-a-project.mdx +++ b/docs/content/Getting-Started/Core/02-Create-a-project.mdx @@ -2,11 +2,14 @@ title: Create a project permalink: /getting-started/core/create-a-project category: Getting Started -subCategory: Core -menuOrder: 4 +subCategory: Cube Core +menuOrder: 3 isDisableFeedbackBlock: true --- +In this step, we will create a Cube Core project on your computer, connect a +data source, and generate data models. + ## Scaffold a project Start by opening your terminal to create a new folder for the project, then @@ -19,13 +22,6 @@ touch docker-compose.yml Open the `docker-compose.yml` file and add the following content: - - -If you're using Linux as the Docker host OS, you'll also need to add -`network_mode: 'host'` to your `docker-compose.yml`. - - - ```yaml version: '2.2' @@ -40,14 +36,19 @@ services: - .:/cube/conf ``` -## Start the development server +Note that we're setting the `CUBEJS_DEV_MODE` environment variable to `true` to +enable the [Development Mode](/configuration/overview#development-mode). This is +handy for local development but not suitable for +[production](/deployment/production-checklist). - + -Using Windows? Remember to use [PowerShell][powershell-docs] or -[WSL2][wsl2-docs] to run the command below. +If you're using Linux as the Docker host OS, you'll also need to add +`network_mode: 'host'` to your `docker-compose.yml`. - + + +## Start the development server From the newly-created project directory, run the following command to start Cube: @@ -56,15 +57,21 @@ Cube: docker-compose up -d ``` + + +Using Windows? Remember to use [PowerShell][powershell-docs] or +[WSL2][wsl2-docs] to run the command below. + + + ## Connect a data source -Head to [http://localhost:4000](http://localhost:4000) to open [Developer +Head to [http://localhost:4000](http://localhost:4000) to open the [Developer Playground][ref-devtools-playground]. -The [Developer Playground][ref-devtools-playground] has a database connection -wizard that loads when Cube is first started up and no `.env` file is found. -After database credentials have been set up, an `.env` file will automatically -be created and populated with the same credentials. +The Playground has a database connection wizard that loads when Cube is first +started up and no `.env` file is found. After database credentials have been set +up, an `.env` file will automatically be created and populated with credentials.
-The next screen shows all the databases Cube can connect to. Click on -**PostgreSQL**, then use the following credentials: + + +Want to use a sample database instead? Select PostgreSQL and use the +credentials below: + +
| Field | Value | | -------- | ------------------ | @@ -85,6 +96,12 @@ The next screen shows all the databases Cube can connect to. Click on | Username | `cube` | | Password | `12345` | + + +After selecting the data source, enter valid credentials for it and +click Apply. Check the [Connecting to Databases][ref-conf-db] +page for more details on specific data sources. +
-After clicking Apply, you should see tables available to you from the configured -database; select the `orders` table to generate a Cube model: +You should see tables available to you from the configured database; select the +`orders` table to generate a data model:
-After selecting the table, click **Generate Schema** and you should see the -following: +After selecting the table, click Generate Schema and you should see +the following:
-Click **Build** on the dialog, which should take you to the **Build** page. +Click Build on the dialog, which should take you to +the Build page. -In the next step, we'll learn how to -[create a model from scratch](/getting-started/core/create-models). +You're now ready for the next step, [querying the +data][ref-getting-started-core-query-cube]. [powershell-docs]: https://learn.microsoft.com/en-us/powershell/ +[ref-conf-db]: /config/databases +[ref-getting-started-core-query-cube]: /getting-started/core/query-data [ref-devtools-playground]: /dev-tools/dev-playground [wsl2-docs]: https://learn.microsoft.com/en-us/windows/wsl/install diff --git a/docs/content/Getting-Started/Core/03-Generate-models.mdx b/docs/content/Getting-Started/Core/03-Generate-models.mdx deleted file mode 100644 index e48df39bcfefc..0000000000000 --- a/docs/content/Getting-Started/Core/03-Generate-models.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Generate models -permalink: /getting-started/core/generate-models -category: Getting Started -subCategory: Core -menuOrder: 4 -isDisableFeedbackBlock: true ---- - -In this step, you will generate models using the connected data source from the -last step. Cube's models provide a declarative way to define important facts -about your data, relationships between them and access control. - -## Select tables - -Start by selecting the database tables to use to generate the models, then click -**Generate Schema**: - -
- Cube's Generate Models Screen showing some tables selected from data source -
- -After the models have been successfully generated, you should see the following -screen: - -
- Screen showing successful generation of models -
- -Click **Build** to continue on the Playground, where you can explore the models -you just created. In the next step, we'll learn more about [how to query -Cube][ref-getting-started-oss-query-cube]. - -[ref-getting-started-oss-query-cube]: /getting-started/core/query-data diff --git a/docs/content/Getting-Started/Core/04-Query-data.mdx b/docs/content/Getting-Started/Core/03-Query-data.mdx similarity index 54% rename from docs/content/Getting-Started/Core/04-Query-data.mdx rename to docs/content/Getting-Started/Core/03-Query-data.mdx index d5d8a99eacb83..69b65e41e87c9 100644 --- a/docs/content/Getting-Started/Core/04-Query-data.mdx +++ b/docs/content/Getting-Started/Core/03-Query-data.mdx @@ -2,25 +2,25 @@ title: Query data permalink: /getting-started/core/query-data category: Getting Started -subCategory: Core -menuOrder: 6 +subCategory: Cube Core +menuOrder: 4 isDisableFeedbackBlock: true --- -In this step, you will learn how to query your data using the models you created -in the previous step. Cube provides several ways to query your data, and we'll -go over them here. +In this step, you will learn how to query your data using the data models you +created in the previous step. Cube provides several ways to query your data, and +we'll go over them here. ## Developer Playground The [Developer Playground](/dev-tools/dev-playground) is a web-based tool which -allows for model generation and data exploration. +allows for model generation and data exploration. On the Build tab, +you can select the measures and dimensions, and then run the query. Let's do +this for the `Orders` cube you generated in the previous step. -Select the measures and dimensions you want to query, and then run the query. -Let's do this for the `Orders` cube you generated in the previous step. - -Click **+ Measure** to display the available measures and add `Orders.count`, -then click **+ Dimension** for available dimensions and add `Orders.status`. +Click + Measure to display the available measures and add +`Orders.count`, then click + Dimension for available dimensions and +add `Orders.status`.
-Then click the **Run** button to execute the query and see the results: +Then, click Run to execute the query and see the results:
SELECT COUNT(*) FROM Orders; 10000 (1 row) ``` + +Since the SQL API is Postgres-compatible, please make sure to +select Postgres as the database type when [connecting from BI +tools][ref-downstream]. + +Now that we've seen how to use Cube's APIs, let's take a look at [how to add +pre-aggregations][next] to speed up your queries. + +[ref-graphql-api]: /backend/graphql +[ref-rest-api]: /rest-api +[ref-downstream]: /config/downstream +[next]: /getting-started/core/add-a-pre-aggregation diff --git a/docs/content/Getting-Started/Core/05-Add-a-pre-aggregation.mdx b/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx similarity index 78% rename from docs/content/Getting-Started/Core/05-Add-a-pre-aggregation.mdx rename to docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx index 10e52981ee8dc..4f643e86e4aa3 100644 --- a/docs/content/Getting-Started/Core/05-Add-a-pre-aggregation.mdx +++ b/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx @@ -2,17 +2,17 @@ title: Add a pre-aggregation permalink: /getting-started/core/add-a-pre-aggregation category: Getting Started -subCategory: Core -menuOrder: 7 +subCategory: Cube Core +menuOrder: 5 isDisableFeedbackBlock: true --- In this step, we'll add a pre-aggregation to optimize the performance of a specific query. Pre-aggregations are a caching technique that massively reduces -query time from seconds to milliseconds, and are extremely useful for speeding +query time from seconds to milliseconds. They are extremely useful for speeding up queries that are run frequently. -From the Developer Playground, execute a query: +From the Build tab, execute a query:
-Just above the results, click on **Query was not accelerated with -pre-aggregation** to bring up the Rollup Designer: +Just above the results, click on Query was not accelerated with +pre-aggregation to bring up the Rollup Designer:
The Rollup Designer will automatically suggest a pre-aggregation for the query; -simply click **Add to the Data Schema** and then retry the query in the +click Add to the Data Schema and then retry the query in the Playground. This time, the query should be accelerated with a pre-aggregation:
diff --git a/docs/content/Getting-Started/Core/05-Learn-more.mdx b/docs/content/Getting-Started/Core/05-Learn-more.mdx new file mode 100644 index 0000000000000..fb99a5c51c46e --- /dev/null +++ b/docs/content/Getting-Started/Core/05-Learn-more.mdx @@ -0,0 +1,41 @@ +--- +title: Learn more +permalink: /getting-started/core/learn-more +category: Getting Started +subCategory: Cube Core +menuOrder: 6 +isDisableFeedbackBlock: true +--- + +Now that you've set up your first project, learn more about what else Cube can +do for you. + +## Data Modeling + +Learn more about [data modeling](/schema/fundamentals/concepts) and how to +effectively define metrics in your data models. Advanced users: check out +[related recipes](/recipes#recipes-data-schema) for tackling specific data +modeling problems. + +## Querying + +Cube can be queried in a variety of ways. Explore how to use +[REST API](/rest-api), [GraphQL API](/backend/graphql), and +[SQL API](/backend/sql), or how to +[connect a BI or data visualization tool](/config/downstream). + +## Caching + +Learn more about the [two-level cache](/docs/caching) and how +[pre-aggregations help speed up queries](/caching/pre-aggregations/getting-started). +For a deeper dive, take a look at the +[related recipes](/recipes#recipes-query-acceleration). + +## Access Control + +Cube uses [JSON Web Tokens](https://jwt.io/) to +[authenticate requests for the HTTP APIs](/security), and +[`checkSqlAuth()`](/config#check-sql-auth) to +[authenticate requests for the SQL API](/backend/sql/security). Cube also +supports using JWT claims for securing access to data, check out these +[related recipes](/recipes#recipes-access-control). diff --git a/docs/content/Getting-Started/Core/06-Learn-more.mdx b/docs/content/Getting-Started/Core/06-Learn-more.mdx deleted file mode 100644 index 961064b2ee7d8..0000000000000 --- a/docs/content/Getting-Started/Core/06-Learn-more.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Learn more -permalink: /getting-started/core/learn-more -category: Getting Started -subCategory: Core -menuOrder: 8 -isDisableFeedbackBlock: true ---- - -Now that you've set up your first project, learn more about what else Cube can -do for you. - -## Access Control - -Cube uses [JSON Web Tokens](https://jwt.io/) to -[authenticate requests for the HTTP APIs](/security), and -[`checkSqlAuth()`](/config#check-sql-auth) to -[authenticate requests for the SQL API](/backend/sql/security). - -Cube also supports using JWT claims for securing access to data, check out these -[related recipes on the topic](/recipes#recipes-access-control). - -## Modeling - -Learn more about [Cube's data model](/schema/fundamentals/concepts) and how to -effectively model your data for flexible and performant querying. For advanced -users, check out [related recipes](/recipes#recipes-data-schema) for tackling -specific modeling problems. - -## Caching - -Learn more about [Cube's two-level cache](/docs/caching), how -[pre-aggregations can help speed up queries](/caching/pre-aggregations/getting-started) -or for a deeper dive, take a look at the -[related recipes](/recipes#recipes-query-acceleration). - -## Querying - -Cube can be queried in a variety of ways. Learn how to query Cube using -[REST API](/rest-api), [GraphQL API](/backend/graphql), [SQL API](/backend/sql), -or how to [connect using one of our visualization tools](/config/downstream). From cb08466b616bcce44b56b586e947494a73f38121 Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Thu, 30 Mar 2023 18:24:23 +0200 Subject: [PATCH 09/13] Lint --- docs/content/Getting-Started/Cloud/04-Query-data.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/content/Getting-Started/Cloud/04-Query-data.mdx b/docs/content/Getting-Started/Cloud/04-Query-data.mdx index 1bd5de469d420..b9c1ce64ccddf 100644 --- a/docs/content/Getting-Started/Cloud/04-Query-data.mdx +++ b/docs/content/Getting-Started/Cloud/04-Query-data.mdx @@ -140,7 +140,9 @@ fierce-bear=> SELECT COUNT(*) FROM Orders; (1 row) ``` -Since the SQL API is Postgres-compatible, please make sure to select Postgres as the database type when [connecting from BI tools][ref-downstream]. +Since the SQL API is Postgres-compatible, please make sure to +select Postgres as the database type when [connecting from BI +tools][ref-downstream]. Now that we've seen how to use Cube's APIs, let's take a look at [how to add pre-aggregations][next] to speed up your queries. From da0683d9fc9d2a8a9a37c8b8f8c7ab01c2c5beb4 Mon Sep 17 00:00:00 2001 From: Hassan Khan Date: Thu, 30 Mar 2023 19:35:16 +0200 Subject: [PATCH 10/13] docs: more --- .../Getting-Started/Cloud/01-Overview.mdx | 1 - .../Cloud/02-Create-a-deployment.mdx | 1 - .../Cloud/03-Generate-models.mdx | 1 - .../Getting-Started/Cloud/04-Query-data.mdx | 1 - .../Cloud/05-Add-a-pre-aggregation.mdx | 1 - .../Getting-Started/Cloud/06-Learn-more.mdx | 1 - .../Getting-Started/Core/01-Overview.mdx | 1 - .../Core/02-Create-a-project.mdx | 5 +- .../Getting-Started/Core/03-Query-data.mdx | 1 - .../Core/04-Add-a-pre-aggregation.mdx | 1 - .../Getting-Started/Core/05-Learn-more.mdx | 1 - docs/content/Getting-Started/Overview.mdx | 2 +- docs/content/Schema/Getting-Started.mdx | 293 ++++++++++++++++++ 13 files changed, 296 insertions(+), 14 deletions(-) create mode 100644 docs/content/Schema/Getting-Started.mdx diff --git a/docs/content/Getting-Started/Cloud/01-Overview.mdx b/docs/content/Getting-Started/Cloud/01-Overview.mdx index 0a7333159894a..d4785a2f0274a 100644 --- a/docs/content/Getting-Started/Cloud/01-Overview.mdx +++ b/docs/content/Getting-Started/Cloud/01-Overview.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/cloud/overview category: Getting Started subCategory: Cube Cloud menuOrder: 2 -isDisableFeedbackBlock: true --- First, we'll create a new deployment, connect it to a database, and generate a diff --git a/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx index a3f0b3110aed7..ad46495d4c6d1 100644 --- a/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx +++ b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/cloud/create-a-deployment category: Getting Started subCategory: Cube Cloud menuOrder: 3 -isDisableFeedbackBlock: true --- In this step, we will create a new deployment in Cube Cloud. A deployment diff --git a/docs/content/Getting-Started/Cloud/03-Generate-models.mdx b/docs/content/Getting-Started/Cloud/03-Generate-models.mdx index 5af9817b77ed5..128abce6e2055 100644 --- a/docs/content/Getting-Started/Cloud/03-Generate-models.mdx +++ b/docs/content/Getting-Started/Cloud/03-Generate-models.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/cloud/generate-models category: Getting Started subCategory: Cube Cloud menuOrder: 4 -isDisableFeedbackBlock: true --- In this step, you will generate data models using the connected data source from diff --git a/docs/content/Getting-Started/Cloud/04-Query-data.mdx b/docs/content/Getting-Started/Cloud/04-Query-data.mdx index b9c1ce64ccddf..f943732f862ad 100644 --- a/docs/content/Getting-Started/Cloud/04-Query-data.mdx +++ b/docs/content/Getting-Started/Cloud/04-Query-data.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/cloud/query-data category: Getting Started subCategory: Cube Cloud menuOrder: 5 -isDisableFeedbackBlock: true --- In this step, you will learn how to query your data using the data models you diff --git a/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx b/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx index 437813f23eb5c..dfd23a1f9adea 100644 --- a/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx +++ b/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/cloud/add-a-pre-aggregation category: Getting Started subCategory: Cube Cloud menuOrder: 6 -isDisableFeedbackBlock: true --- In this step, we'll add a pre-aggregation to optimize the performance of a diff --git a/docs/content/Getting-Started/Cloud/06-Learn-more.mdx b/docs/content/Getting-Started/Cloud/06-Learn-more.mdx index 76ae22720be81..f0d8a56733100 100644 --- a/docs/content/Getting-Started/Cloud/06-Learn-more.mdx +++ b/docs/content/Getting-Started/Cloud/06-Learn-more.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/cloud/learn-more category: Getting Started subCategory: Cube Cloud menuOrder: 7 -isDisableFeedbackBlock: true --- Now that you've set up your first deployment, learn more about other Cube Cloud diff --git a/docs/content/Getting-Started/Core/01-Overview.mdx b/docs/content/Getting-Started/Core/01-Overview.mdx index 077a9cf6f922e..f07e11d15396b 100644 --- a/docs/content/Getting-Started/Core/01-Overview.mdx +++ b/docs/content/Getting-Started/Core/01-Overview.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/core/overview category: Getting Started subCategory: Cube Core menuOrder: 2 -isDisableFeedbackBlock: true --- First, we'll create a new project, connect it to a database and generate a data diff --git a/docs/content/Getting-Started/Core/02-Create-a-project.mdx b/docs/content/Getting-Started/Core/02-Create-a-project.mdx index 9cc4ee34a986d..1d240eefbb77e 100644 --- a/docs/content/Getting-Started/Core/02-Create-a-project.mdx +++ b/docs/content/Getting-Started/Core/02-Create-a-project.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/core/create-a-project category: Getting Started subCategory: Cube Core menuOrder: 3 -isDisableFeedbackBlock: true --- In this step, we will create a Cube Core project on your computer, connect a @@ -41,12 +40,12 @@ enable the [Development Mode](/configuration/overview#development-mode). This is handy for local development but not suitable for [production](/deployment/production-checklist). - + If you're using Linux as the Docker host OS, you'll also need to add `network_mode: 'host'` to your `docker-compose.yml`. - + ## Start the development server diff --git a/docs/content/Getting-Started/Core/03-Query-data.mdx b/docs/content/Getting-Started/Core/03-Query-data.mdx index 69b65e41e87c9..71e80b2768d43 100644 --- a/docs/content/Getting-Started/Core/03-Query-data.mdx +++ b/docs/content/Getting-Started/Core/03-Query-data.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/core/query-data category: Getting Started subCategory: Cube Core menuOrder: 4 -isDisableFeedbackBlock: true --- In this step, you will learn how to query your data using the data models you diff --git a/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx b/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx index 4f643e86e4aa3..83ad8bd1c27cd 100644 --- a/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx +++ b/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/core/add-a-pre-aggregation category: Getting Started subCategory: Cube Core menuOrder: 5 -isDisableFeedbackBlock: true --- In this step, we'll add a pre-aggregation to optimize the performance of a diff --git a/docs/content/Getting-Started/Core/05-Learn-more.mdx b/docs/content/Getting-Started/Core/05-Learn-more.mdx index fb99a5c51c46e..9bd0238b9e13d 100644 --- a/docs/content/Getting-Started/Core/05-Learn-more.mdx +++ b/docs/content/Getting-Started/Core/05-Learn-more.mdx @@ -4,7 +4,6 @@ permalink: /getting-started/core/learn-more category: Getting Started subCategory: Cube Core menuOrder: 6 -isDisableFeedbackBlock: true --- Now that you've set up your first project, learn more about what else Cube can diff --git a/docs/content/Getting-Started/Overview.mdx b/docs/content/Getting-Started/Overview.mdx index c044162567885..2ea4240c14233 100644 --- a/docs/content/Getting-Started/Overview.mdx +++ b/docs/content/Getting-Started/Overview.mdx @@ -3,7 +3,7 @@ title: Overview permalink: /getting-started category: Getting Started menuOrder: 1 -isDisableFeedbackBlock: true +isDisableFeedbackBlock: false --- You can get started with Cube in one of two ways. diff --git a/docs/content/Schema/Getting-Started.mdx b/docs/content/Schema/Getting-Started.mdx new file mode 100644 index 0000000000000..0f4694de717a3 --- /dev/null +++ b/docs/content/Schema/Getting-Started.mdx @@ -0,0 +1,293 @@ +--- +title: Getting Started with Data Modeling +menuTitle: Getting Started +permalink: /schema/getting-started +category: Reference +menuOrder: 1 +proofread: 06/18/2019 +redirect_from: + - /getting-started-cubejs-schema +--- + + + We're excited to expand the beta of YAML and Python support in Cube data modeling.
+ Please reach out to us if you’d like to sign up for early access. + + +A Cube Data Schema is used to model raw data into meaningful business +definitions and pre-aggregate data for optimal results. The data schema is +exposed through the [querying API][ref-backend-restapi] that allows end-users to +query a wide variety of analytical queries without modifying the schema itself. + +Let’s use a users table with the following columns as an example: + +| id | paying | city | company_name | +| --- | ------ | ------------- | ------------ | +| 1 | true | San Francisco | Pied Piper | +| 2 | true | Palo Alto | Raviga | +| 3 | true | Redwood | Aviato | +| 4 | false | Mountain View | Bream-Hall | +| 5 | false | Santa Cruz | Hooli | + +We can start with a set of simple questions about users we want to answer: + +- How many users do we have? +- How many paying users? +- What is the percentage of paying users out of the total? +- How many users, paying or not, are from different cities and companies? + +We don’t need to write SQL queries for every question, since the data schema +allows building well-organized and reusable SQL. + +## 1. Creating a Cube + +In Cube, [cubes][ref-schema-cube] are used to organize entities and +connections between entities. Usually one cube is created for each table in the +database, such as `users`, `orders`, `products`, etc. In the `sql` parameter of +the cube we define a base table for this cube. In our case, the base table is +simply our `users` table. + + + +```javascript +cube(`Users`, { + sql: `SELECT * FROM users`, +}); +``` + +```yaml +cubes: + - name: Users + sql: SELECT * FROM users +``` + + + +## 2. Adding Measures and Dimensions + +Once the base table is defined, the next step is to add +[measures][ref-schema-measures] and [dimensions][ref-schema-dimensions] to the +cube. + + + +**Measures** are referred to as quantitative data, such as number of units sold, +number of unique visits, profit, and so on. + +**Dimensions** are referred to as categorical data, such as state, gender, +product name, or units of time (e.g., day, week, month). + + + +Let's go ahead and create our first measure and two dimensions: + + + +```javascript +cube(`Users`, { + sql: `SELECT * FROM users`, + + measures: { + count: { + sql: `id`, + type: `count`, + }, + }, + + dimensions: { + city: { + sql: `city`, + type: `string`, + }, + + company_name: { + sql: `company_name`, + type: `string`, + }, + }, +}); +``` + +```yaml +cubes: + - name: Users + sql: SELECT * FROM users + measures: + - name: count + sql: id + type: count + dimensions: + - name: city + sql: city + type: string + - name: company_name + sql: company_name + type: string +``` + + + +Let's break down the above code snippet piece-by-piece. After defining the base +table for the cube (with the `sql` property), we create a `count` measure in the +`measures` block. [The type][ref-schema-types-formats] `count` and sql `id` +means that when this measure will be requested via an API, Cube will generate +and execute the following SQL: + +```sql +SELECT count(id) from users; +``` + +When we apply a city dimension to the measure to see "Where are users based?", +Cube will generate SQL with a `GROUP BY` clause: + +```sql +SELECT city, count(id) from users GROUP BY 1; +``` + +You can add as many dimensions as you want to your query when you perform +grouping. + +## 3. Adding Filters to Measures + +Now let's answer the next question – "How many paying users do we have?". To +accomplish this, we will introduce **measure filters**: + + + +```javascript +cube(`Users`, { + measures: { + count: { + sql: `id`, + type: `count`, + }, + + paying_count: { + sql: `id`, + type: `count`, + filters: [{ sql: `${CUBE}.paying = 'true'` }], + }, + }, +}); +``` + +```yaml +cubes: + - name: Users + measures: + - name: count + sql: id + type: count + - name: paying_count + sql: id + type: count + filters: + - sql: "{CUBE}.paying = 'true'" +``` + + + + + +It is best practice to prefix references to table columns with the name of the +cube or with the `CUBE` constant when referencing the current cube's column. + + + +That's it! Now we have the `paying_count` measure, which shows only our paying +users. When this measure is requested, Cube will generate the following SQL: + +```sql +SELECT + count( + CASE WHEN (users.paying = 'true') THEN users.id END + ) "users.paying_count" +FROM users +``` + +Since the `filters` property is an array, you can apply as many filters as +required. `paying_count` can be used with dimensions the same way as a simple +`count`. We can group `paying_count` by `city` and `companyName` simply by adding +these dimensions alongside measures in the requested query. + +## 4. Using Calculated Measures + +To answer "What is the percentage of paying users out of the total?", we need to +calculate the paying users ratio, which is basically `paying_count / count`. +Cube makes it extremely easy to perform this kind of calculation. Let's add a +new measure to our cube called `paying_percentage`: + + + +```javascript +cube(`Users`, { + measures: { + count: { + sql: `id`, + type: `count`, + }, + + paying_count: { + sql: `id`, + type: `count`, + filters: [{ sql: `${CUBE}.paying = 'true'` }], + }, + + paying_percentage: { + sql: `100.0 * ${paying_count} / ${count}`, + type: `number`, + format: `percent`, + }, + }, +}); +``` + +```yaml +cubes: + - name: Users + measures: + - name: count + sql: id + type: count + - name: paying_count + sql: id + type: count + filters: + - sql: "{CUBE}.paying = 'true'" + - name: paying_percentage + sql: "100.0 * {paying_count} / {count}" + type: number + format: percent +``` + + + +Here we defined a calculated measure `paying_percentage`, which divides +`paying_count` by `count`. This example shows how you can reference measures +inside other measure definitions. When you request the `paying_percentage` +measure via an API, the following SQL will be generated: + +```sql +SELECT + 100.0 * count( + CASE WHEN (users.paying = 'true') THEN users.id END + ) / count(users.id) "users.paying_percentage" +FROM users +``` + +As with other measures, `paying_percentage` can be used with dimensions. + +## 5. Next Steps + +1. [Examples][ref-examples] +2. [Query format][ref-backend-query-format] +3. [REST API][ref-backend-restapi] +4. [Schema reference documentation][ref-schema-cube] + +[ref-backend-restapi]: /rest-api +[ref-schema-cube]: /schema/reference/cube +[ref-schema-measures]: /schema/reference/measures +[ref-schema-dimensions]: /schema/reference/dimensions +[ref-schema-types-formats]: /schema/reference/types-and-formats +[ref-examples]: /examples +[ref-backend-query-format]: /query-format From c200e26989ed3ad937082eb1f5367e229861acd9 Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Fri, 31 Mar 2023 12:22:48 +0200 Subject: [PATCH 11/13] Fix --- docs/content/Getting-Started/Core/02-Create-a-project.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/content/Getting-Started/Core/02-Create-a-project.mdx b/docs/content/Getting-Started/Core/02-Create-a-project.mdx index 1d240eefbb77e..5b3a7fb89a324 100644 --- a/docs/content/Getting-Started/Core/02-Create-a-project.mdx +++ b/docs/content/Getting-Started/Core/02-Create-a-project.mdx @@ -53,7 +53,7 @@ From the newly-created project directory, run the following command to start Cube: ```bash{promptUser: user} -docker-compose up -d +docker compose up -d ``` @@ -120,8 +120,9 @@ You should see tables available to you from the configured database; select the />
-After selecting the table, click Generate Schema and you should see -the following: +After selecting the table, click Generate Schema and pick +either YAML (recommended) or JavaScript format. You +should see the following:
Date: Fri, 31 Mar 2023 16:25:23 +0200 Subject: [PATCH 12/13] docs: fixup --- .../Getting-Started/Core/03-Query-data.mdx | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/content/Getting-Started/Core/03-Query-data.mdx b/docs/content/Getting-Started/Core/03-Query-data.mdx index 71e80b2768d43..27d13fa769db0 100644 --- a/docs/content/Getting-Started/Core/03-Query-data.mdx +++ b/docs/content/Getting-Started/Core/03-Query-data.mdx @@ -65,24 +65,25 @@ curl \ ## SQL API -To enable the SQL API, we first need to add a few new environment variables to -the project's `.env` file: - -```bash -CUBEJS_PG_SQL_PORT=5432 -CUBEJS_SQL_USER=myusername -CUBEJS_SQL_PASSWORD=mypassword -``` - -If you're running Cube through Docker Compose, remember to add a port mapping to -the Cube service for `CUBEJS_PG_SQL_PORT`: +To enable the SQL API, we first need to add a few new environment variables. +Let's add them to the `docker-compose.yml` file: ```yaml +version: '2.2' + services: cube: - image: cubejs/cube + image: cubejs/cube:latest ports: - - 5432:5432 # Cube SQL API + - 4000:4000 # Playground + - 5432:5432 # SQL API + environment: + - CUBEJS_DEV_MODE=true + - CUBEJS_PG_SQL_PORT=5432 + - CUBEJS_SQL_USER=myusername + - CUBEJS_SQL_PASSWORD=mypassword + volumes: + - .:/cube/conf ``` You can connect via the `psql` client with provided credentials: From aad037be4bb998b084d13ffb7959799d0e2d8ebc Mon Sep 17 00:00:00 2001 From: Hassan Khan Date: Fri, 31 Mar 2023 16:28:53 +0200 Subject: [PATCH 13/13] docs: fixup --- docs/content/Getting-Started/Core/01-Overview.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/content/Getting-Started/Core/01-Overview.mdx b/docs/content/Getting-Started/Core/01-Overview.mdx index f07e11d15396b..e8a88829a07d3 100644 --- a/docs/content/Getting-Started/Core/01-Overview.mdx +++ b/docs/content/Getting-Started/Core/01-Overview.mdx @@ -14,7 +14,6 @@ milliseconds. This guide will walk you through the following tasks: - [Create a new project](/getting-started/core/create-a-project) -- [Generate a data model from a connected data source](/getting-started/core/generate-models) - [Run queries using the Developer Playground and APIs](/getting-started/core/query-data) - [Add a pre-aggregation to optimize query performance](/getting-started/core/add-a-pre-aggregation)