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..d4785a2f0274a --- /dev/null +++ b/docs/content/Getting-Started/Cloud/01-Overview.mdx @@ -0,0 +1,24 @@ +--- +title: Getting started with Cube Cloud +permalink: /getting-started/cloud/overview +category: Getting Started +subCategory: Cube Cloud +menuOrder: 2 +--- + +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: + +- [Create a new deployment](/getting-started/cloud/create-a-deployment) +- [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 +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..ad46495d4c6d1 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx @@ -0,0 +1,125 @@ +--- +title: Create a deployment +permalink: /getting-started/cloud/create-a-deployment +category: Getting Started +subCategory: Cube Cloud +menuOrder: 3 +--- + +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. + +## Create a deployment + +First, [sign in to your Cube Cloud account][cube-cloud-signin]. Then, +click Create Deployment: + +
+ Cube Cloud Landing Screen with no configured deployments +
+ +Give the deployment a name, select the cloud provider and region of your choice, +and click Next: + +
+ Cube Cloud Create Deployment Screen +
+ +## Set up a 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. First, select the data source from the grid: + +
+ Cube Cloud Setup Database Screen +
+ + + +Want to use a sample database instead? Select PostgreSQL and use the +credentials below: + +
+ +| Field | Value | +| -------- | ------------------ | +| Host | `demo-db.cube.dev` | +| Port | `5432` | +| Database | `ecom` | +| 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. + +
+ 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 data +models][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..128abce6e2055 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/03-Generate-models.mdx @@ -0,0 +1,104 @@ +--- +title: Generate data models +permalink: /getting-started/cloud/generate-models +category: Getting Started +subCategory: Cube Cloud +menuOrder: 4 +--- + +In this step, you will generate data models using the connected data source from +the last step. + +Cube's data models provide a declarative way to define important facts about +your data and relationships between them. You can create data models from +scratch or let Cube generate an initial version for you. + +## 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 relationships 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 (recommended) or JavaScript format 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 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 new file mode 100644 index 0000000000000..f943732f862ad --- /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 +--- + +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 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. + +Navigate to 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, 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 + +First, navigate to the Settings page and enable the SQL API. + +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: + +
+ +
+ +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 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/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..dfd23a1f9adea --- /dev/null +++ b/docs/content/Getting-Started/Cloud/05-Add-a-pre-aggregation.mdx @@ -0,0 +1,57 @@ +--- +title: Add a pre-aggregation +permalink: /getting-started/cloud/add-a-pre-aggregation +category: Getting Started +subCategory: Cube Cloud +menuOrder: 6 +--- + +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. They are extremely useful for speeding +up queries that are run frequently. + +From the Developer Playground page, 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; +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. + +
+ 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..f0d8a56733100 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/06-Learn-more.mdx @@ -0,0 +1,34 @@ +--- +title: Learn more +permalink: /getting-started/cloud/learn-more +category: Getting Started +subCategory: Cube Cloud +menuOrder: 7 +--- + +Now that you've set up your first deployment, learn more about other Cube Cloud +feaures. + +## Access Control + +Invite your team to collaborate in Cube Cloud and fine-tune their access to +deployments and features with +[role-based access control](/cloud/access-control/). You can create and manage +multiple deployments, each with their own set of users. + +## Team collaboration + +Cube Cloud has a [web-based IDE](/cloud/workspace/cube-ide) that can be used to +make changes to data models and test them in a development environment. + +You can also connect [Cube Cloud to Git](/cloud/deploys) to sync and deploy from +your repository. + +## Observability + +The [Queries](/cloud/inspecting-queries) page in Cube Cloud provides query-level +observability, allowing to detect and remedy performance issues 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. 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..e8a88829a07d3 --- /dev/null +++ b/docs/content/Getting-Started/Core/01-Overview.mdx @@ -0,0 +1,23 @@ +--- +title: Getting started with Cube Core +permalink: /getting-started/core/overview +category: Getting Started +subCategory: Cube Core +menuOrder: 2 +--- + +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) +- [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 +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..5b3a7fb89a324 --- /dev/null +++ b/docs/content/Getting-Started/Core/02-Create-a-project.mdx @@ -0,0 +1,145 @@ +--- +title: Create a project +permalink: /getting-started/core/create-a-project +category: Getting Started +subCategory: Cube Core +menuOrder: 3 +--- + +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 +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: + +```yaml +version: '2.2' + +services: + cube: + image: cubejs/cube:latest + ports: + - 4000:4000 + environment: + - CUBEJS_DEV_MODE=true + volumes: + - .:/cube/conf +``` + +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). + + + +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: + +```bash{promptUser: user} +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 the [Developer +Playground][ref-devtools-playground]. + +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. + +
+ +
+ + + +Want to use a sample database instead? Select PostgreSQL and use the +credentials below: + +
+ +| Field | Value | +| -------- | ------------------ | +| Host | `demo-db.cube.dev` | +| Port | `5432` | +| Database | `ecom` | +| 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. + +
+ +
+ +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 pick +either YAML (recommended) or JavaScript format. You +should see the following: + +
+ +
+ +Click Build on the dialog, which should take you to +the Build page. + +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-Query-data.mdx b/docs/content/Getting-Started/Core/03-Query-data.mdx new file mode 100644 index 0000000000000..27d13fa769db0 --- /dev/null +++ b/docs/content/Getting-Started/Core/03-Query-data.mdx @@ -0,0 +1,115 @@ +--- +title: Query data +permalink: /getting-started/core/query-data +category: Getting Started +subCategory: Cube Core +menuOrder: 4 +--- + +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. 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. + +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 Run to execute the query and see the results: + +
+ Cube Cloud Deployment Developer Playground Screen showing query results +
+ +## GraphQL API + +Cube provides the [GraphQL API][ref-graphql-api] to query cubes via the +`/graphql` endpoint: + +```bash{outputLines: 2-4} +curl \ + --data-raw '{"query":"{cube{orders{count}}}"}' \ + http://localhost:4000/cubejs-api/graphql +``` + +## REST API + +Cube supports using the [REST API][ref-rest-api] to query cubes via the `/load` +endpoint: + +```bash{outputLines: 2-4} +curl \ + --data-urlencode 'query={"measures":["Orders.count"]}' \ + http://localhost:4000/cubejs-api/v1/load +``` + +## SQL API + +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:latest + ports: + - 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: + +```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) +``` + +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/04-Add-a-pre-aggregation.mdx b/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx new file mode 100644 index 0000000000000..83ad8bd1c27cd --- /dev/null +++ b/docs/content/Getting-Started/Core/04-Add-a-pre-aggregation.mdx @@ -0,0 +1,53 @@ +--- +title: Add a pre-aggregation +permalink: /getting-started/core/add-a-pre-aggregation +category: Getting Started +subCategory: Cube Core +menuOrder: 5 +--- + +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. They are extremely useful for speeding +up queries that are run frequently. + +From the Build tab, 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; +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/05-Learn-more.mdx b/docs/content/Getting-Started/Core/05-Learn-more.mdx new file mode 100644 index 0000000000000..9bd0238b9e13d --- /dev/null +++ b/docs/content/Getting-Started/Core/05-Learn-more.mdx @@ -0,0 +1,40 @@ +--- +title: Learn more +permalink: /getting-started/core/learn-more +category: Getting Started +subCategory: Cube Core +menuOrder: 6 +--- + +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/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..2ea4240c14233 100644 --- a/docs/content/Getting-Started/Overview.mdx +++ b/docs/content/Getting-Started/Overview.mdx @@ -1,29 +1,32 @@ --- -title: Getting Started +title: Overview permalink: /getting-started category: Getting Started menuOrder: 1 -isDisableFeedbackBlock: true +isDisableFeedbackBlock: false --- -You can get started with Cube locally or self-host it with Docker. +You can get started with Cube in one of two ways. -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. +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. + + + -There's also a legacy option to get started with -[Node.js](getting-started/nodejs). +[cube-cloud]: https://cube.dev/cloud/ 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/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/_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; } 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;