diff --git a/docs/content/Getting-Started/Cloud/01-Overview.mdx b/docs/content/Getting-Started/Cloud/01-Overview.mdx index d4785a2f0274a..a531d6aa0972b 100644 --- a/docs/content/Getting-Started/Cloud/01-Overview.mdx +++ b/docs/content/Getting-Started/Cloud/01-Overview.mdx @@ -6,19 +6,16 @@ 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 getting started guide will show you how to use Cube Cloud with Snowflake. You will learn how to: -This guide will walk you through the following tasks: +- Load sample data into your Snowflake account +- Connect Cube Cloud to Snowflake +- Create your first Cube data model +- Connect to a BI tool to explore this model +- Create React application with Cube REST API -- [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) +## Prerequisites -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 +- [Cube Cloud account](https://cubecloud.dev/auth/signup) +- [Snowflake account](https://signup.snowflake.com/) diff --git a/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx b/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx deleted file mode 100644 index 2608b9537c3cd..0000000000000 --- a/docs/content/Getting-Started/Cloud/02-Create-a-deployment.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -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: - - - -Give the deployment a name, select the cloud provider and region of your choice, -and click Next: - - - - - -Microsoft Azure is available in Cube Cloud on -[Premium](https://cube.dev/pricing) tier. [Contact us](https://cube.dev/contact) -for details. - - - -## Set up a Cube project - -Next, click Create to create a new project from scratch: - - - -## 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: - - - - - -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. - - - -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/02-Load data.mdx b/docs/content/Getting-Started/Cloud/02-Load data.mdx new file mode 100644 index 0000000000000..076ab35067e29 --- /dev/null +++ b/docs/content/Getting-Started/Cloud/02-Load data.mdx @@ -0,0 +1,108 @@ +--- +title: Load data +permalink: /getting-started/cloud/load-data +category: Getting Started +subCategory: Cube Cloud +menuOrder: 2.1 +--- + +The following steps will guide you through setting up a Snowflake account and uploading the demo dataset, which is stored as CSV files in a public S3 bucket. + +First, let’s create a warehouse, database, and schema. Paste the following SQL into the Editor of the Snowflake worksheet and click Run. + +```sql +CREATE WAREHOUSE cube_demo_wh; +CREATE DATABASE cube_demo; +CREATE SCHEMA cube_demo.ecom; +``` + +We’re going to create four tables in the `ecom` schema and seed them with data from S3. + +First, let’s create `line_items` table. Delete the previous SQL in your Editor and then run the following command. + +```sql +CREATE TABLE cube_demo.ecom.line_items +( id INTEGER, + order_id INTEGER, + product_id INTEGER, + price INTEGER, + created_at TIMESTAMP +); +``` + +Clear all the content in the Editor and run the following command to load data into the `line_items` table. + +``` +COPY INTO cube_demo.ecom.line_items (id, order_id, product_id, price, created_at) +FROM 's3://cube-tutorial/line_items.csv' +FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = ',' SKIP_HEADER = 1); +``` + +Now, we’re going to repeat these steps for three other tables. + +Run the following command to create the `orders` table. + +```sql +CREATE TABLE cube_demo.ecom.orders +( id INTEGER, + user_id INTEGER, + status VARCHAR, + completed_at TIMESTAMP, + created_at TIMESTAMP +); +``` + +Run the following command to load data into the `orders` table from S3. + +```sql +COPY INTO cube_demo.ecom.orders (id, user_id, status, completed_at, created_at) +FROM 's3://cube-tutorial/orders.csv' +FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = ',' SKIP_HEADER = 1); + +``` + +Run the following command to create the `users` table. + +```sql +CREATE TABLE cube_demo.ecom.users +( id INTEGER, + user_id INTEGER, + city VARCHAR, + age INTEGER, + gender VARCHAR, + state VARCHAR, + first_name VARCHAR, + last_name VARCHAR, + created_at TIMESTAMP +); + +``` + +Run the following command to load data into the `users` table. + +```sql +COPY INTO cube_demo.ecom.users (id, city, age, gender, state, first_name, last_name, created_at) +FROM 's3://cube-tutorial/users.csv' +FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = ',' SKIP_HEADER = 1); + +``` + +Run the following command to create the `products` table. + +```sql +CREATE TABLE cube_demo.ecom.products +( id INTEGER, + name VARCHAR, + product_category VARCHAR, + created_at TIMESTAMP +); + +``` + +Run the following command to load data into the `products` table. + +```sql +COPY INTO cube_demo.ecom.products (id, name, created_at, product_category) +FROM 's3://cube-tutorial/products.csv' +FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = ',' SKIP_HEADER = 1); +``` \ No newline at end of file diff --git a/docs/content/Getting-Started/Cloud/03-Connect-to-Snowflake.mdx b/docs/content/Getting-Started/Cloud/03-Connect-to-Snowflake.mdx new file mode 100644 index 0000000000000..d5d81d8b600bf --- /dev/null +++ b/docs/content/Getting-Started/Cloud/03-Connect-to-Snowflake.mdx @@ -0,0 +1,77 @@ +--- +title: Connect to Snowflake +permalink: /getting-started/cloud/connect-to-snowflake +category: Getting Started +subCategory: Cube Cloud +menuOrder: 3 +--- + +In this section, we’ll create a Cube Cloud deployment and connect it to Snowflake. +A deployment represents a data model, configuration, and managed infrastructure. + +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. + +First, [sign in to your Cube Cloud account][cube-cloud-signin]. Then, +click Create Deployment: + +Give the deployment a name, select the cloud provider and region of your choice, +and click Next: + + + + + +Microsoft Azure is available in Cube Cloud on +[Premium](https://cube.dev/pricing) tier. [Contact us](https://cube.dev/contact) +for details. + + + +## Set up a Cube project + +Next, click Create to create a new project from scratch: + + + +## Connect to your Snowflake + +The last step is to connect Cube Cloud to Snowflake. First, select it from the grid: + + + +Then enter your Snowflake credentials: + +- **Username:** Your Snowflake username. Please note, it is usually **not** your email address. +- **Password:** Your Snowflake password. +- **Database:** `CUBE_DEMO`, that is the database we've created in the previous step. +- **Account:** Your snowflake account identifier. You can find it in your Snowflake URL as the `account_locator` part. +- **Region:** Your Snowflake account region. You can find it in your Snowflake URL. If your URL includes a `cloud` part, use both the `cloud_region_id` and `cloud` together e.g. `us-east-2.aws`, otherwise just use `cloud_region_id` +- **Warehouse:** `CUBE_DEMO_WH`, that is the warehouse we've created in the previous step. +- **Role:** You can leave it blank. + +Click Apply, Cube Cloud will test the connection and proceed to the next step. + +## Generate data model from your Snowflake schema + +Cube can now generate a basic data model from your data warehouse schema, which helps getting started with data modeling faster. +Select all four tables in our `ECOM` schema and click through the data model generation wizard. We'll inspect these generated files in the next section and start making changes to them. + +[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 deleted file mode 100644 index a8104be38141d..0000000000000 --- a/docs/content/Getting-Started/Cloud/03-Generate-models.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -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 models from, then -click Measures and Dimensions: - - - -## 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: - - - -## Primary keys - -Review the detected primary keys for each cube and click Joins to -move to the next step: - - - -## Joins - -Once again, review the detected joins and relationships and -click Review: - - - -## 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 will now generate the models and spin up your Cube deployment, and in -a few moments you should see the following 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-Create-data-model.mdx b/docs/content/Getting-Started/Cloud/04-Create-data-model.mdx new file mode 100644 index 0000000000000..7f5d2e989475d --- /dev/null +++ b/docs/content/Getting-Started/Cloud/04-Create-data-model.mdx @@ -0,0 +1,179 @@ +--- +title: Create your first data model +permalink: /getting-started/cloud/create-data-model +category: Getting Started +subCategory: Cube Cloud +menuOrder: 4 +--- + +Cube follows a dataset-oriented data modeling approach, which is inspired by and expands upon dimensional modeling. +Cube incorporates this approach and provides a practical framework for implementing dataset-oriented data modeling. + +When building a data model in Cube, you work with two dataset-centric objects: **cubes** and **views**. +**Cubes** usually represent business entities such as customers, line items, and orders. +In cubes, you define all the calculations within the measures and dimensions of these entities. +Additionally, you define relationships between cubes, such as "an order has many line items" or "a user may place multiple orders." + +**Views** sit on top of a data graph of cubes and create a facade of your entire data model, with which data consumers can interact. +You can think of views as the final data products for your data consumers - BI users, data apps, AI agents, etc. +When building views, you select measures and dimensions from different connected cubes and present them as a single dataset to BI or data apps. + + + +## Working with cubes + +To begin building your data model, click on Enter Development Mode in Cube Cloud. This will take you to your personal developer space, where you can safely make changes to your data model without affecting the production environment. + +In the previous section, we generated four cubes from the Snowflake schema. To see the data graph of these four cubes and how they are connected to each other, click the Show Graph button on the Data Model page. + +Let's review the `orders` cube first and update it with additional dimensions and measures. + +Once you are in developer mode, navigate to the Data Model and click on the `orders.yml` file in the left sidebar inside the `model/cubes` directory to open it. + +You should see the following content of `model/cubes/orders.yml` file. + +```yaml +cubes: + - name: orders + sql_table: ECOM.ORDERS + + joins: + - name: users + sql: "{CUBE}.USER_ID = {users}.USER_ID" + relationship: many_to_one + + dimensions: + - name: status + sql: STATUS + type: string + + - name: id + sql: ID + type: number + primary_key: true + + - name: created_at + sql: CREATED_AT + type: time + + - name: completed_at + sql: COMPLETED_AT + type: time + + measures: + - name: count + type: count +``` + +As you can see, we already have a `count` measure that we can use to calculate the total count of our orders. + +Let's add an additional measure to the `orders` cube to calculate only **completed orders**. +The `status` dimension in the `orders` cube reflects the three possible statuses: **processing**, **shipped**, or **completed**. +We will create a new measure `completed_count` by using a filter on that dimension. +To do this, we will use a [filter parameter](/schema/reference/measures#parameters-filters) of the measure +and [refer](/data-modeling/syntax#referring-to-objects) to the existing dimension. + +Add the following measure definition to your `model/cubes/orders.yml` file. It should be included within the `measures` block. + +```yaml +- name: completed_count + type: count + filters: + - sql: "{CUBE}.status = 'completed'" +``` + +With these two measures in place, `count` and `completed_count`, we can create a **derived measure**. Derived measures are measures that you can create based on existing measures. Let's create the `completed_percentage` derived measure. + +Add the following measure definition to your `model/cubes/orders.yml` file within the `measures` block. + +```yaml +- name: completed_percentage + type: number + sql: "({completed_count} / NULLIF({count}, 0)) * 100.0" + format: percent +``` + +Below you can see what your updated `orders` cube should look like with two new measures. Feel free to copy this code and paste it into your `model/cubes/order.yml` file. + +```yaml +cubes: + - name: orders + sql_table: ECOM.ORDERS + + joins: + - name: users + sql: "{CUBE}.USER_ID = {users}.USER_ID" + relationship: many_to_one + + dimensions: + - name: status + sql: STATUS + type: string + + - name: id + sql: ID + type: number + primary_key: true + + - name: created_at + sql: CREATED_AT + type: time + + - name: completed_at + sql: COMPLETED_AT + type: time + + measures: + - name: count + type: count + + - name: completed_count + type: count + filters: + - sql: "{CUBE}.status = 'completed'" + + - name: completed_percentage + type: number + sql: "({completed_count} / NULLIF({count}, 0)) * 100.0" + format: percent +``` + +Click Save All in the upper corner to save changes to the data model. Now, you can navigate to Cube’s Playground. The Playground is a web-based tool that allows you to query your data without connecting any tools or writing any code. It's the fastest way to explore and test your data model. + +You can select measures and dimensions from different cubes in playground, including your newly created `completed_percentage` measure. + +## Working with views + +When building views, we recommend following entity-oriented design and structuring your views around your business entities. Usually, cubes tend to be normalized entities without duplicated or redundant members, while views are denormalized entities where you pick as many measures and dimensions from multiple cubes as needed to describe a business entity. + +Let's create our first view, which will provide all necessary measures and dimensions to explore orders. Views are usually located in the `views` folder and have a `_view` postfix. + +Create `model/views/orders_view.yml` with the following content: + +```yaml +views: + - name: orders_view + + cubes: + - join_path: orders + includes: + - status + - created_at + - count + - completed_count + - completed_percentage + + - join_path: orders.users + prefix: true + includes: + - city + - age + - state +``` + +When building views, you can leverage the `cubes` parameter, which enables you to include measures and dimensions from other cubes in the view. You can build your view by combining multiple joined cubes and specifying the path by which they should be joined for that particular view. + +After saving, you can experiment with your newly created view in the Playground. In the next section, we will learn how to query our `orders_view` using a BI tool. \ No newline at end of file diff --git a/docs/content/Getting-Started/Cloud/04-Query-data.mdx b/docs/content/Getting-Started/Cloud/04-Query-data.mdx deleted file mode 100644 index 2cc9f893d69fb..0000000000000 --- a/docs/content/Getting-Started/Cloud/04-Query-data.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -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: - - - -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: - - - -Next, click + Dimension for available dimensions, add -`orders.status`, and then click Run again: - - - -Please feel free to experiment: select other measures or dimensions, pick a -granularity for the time dimension instead of w/o grouping, or -choose another chart type instead of Table. - -## GraphQL API - -From the deployment's Overview page, you can copy the GraphQL API URL for the -deployment: - - - -To see an example of how to query the GraphQL API using `curl`, click How -to connect your application: - - - -## REST API - - - -To see an example of how to query the REST API using `curl`, click How to -connect your application: - - - -## 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 index 80990c9b66f34..4d60c9c4845b5 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 @@ -1,7 +1,7 @@ --- title: Add a pre-aggregation permalink: /getting-started/cloud/add-a-pre-aggregation -category: Getting Started +category: NON-EXISTENT subCategory: Cube Cloud menuOrder: 6 --- diff --git a/docs/content/Getting-Started/Cloud/05-Query-from-BI.mdx b/docs/content/Getting-Started/Cloud/05-Query-from-BI.mdx new file mode 100644 index 0000000000000..59d953a93ae8f --- /dev/null +++ b/docs/content/Getting-Started/Cloud/05-Query-from-BI.mdx @@ -0,0 +1,87 @@ +--- +title: Query from BI +permalink: /getting-started/cloud/query-from-BI +category: Getting Started +subCategory: Cube Cloud +menuOrder: 5 +--- + +You can query Cube using a BI or visualization tool through the Cube SQL API. +To provide a good end-user experience in your BI tool, we recommend mapping the BI's data model to Cube's semantic layer. +This can be done automatically with Semantic Layer Sync or manually. + +## Semantic Layer Sync + +Semantic Layer Sync programmatically connects a BI tool to Cube and creates or updates BI-specific entities +that correspond to entities within the data model in Cube, such as cubes, views, measures, and dimensions. + + + +Semantic Layer Sync will synchronize all public cubes and views with connected BI tools. +We recommend making your cubes private and only exposing views. Both cubes and views are public by default. +To make cubes private, set the [public](/schema/reference/cube#parameters-public) parameter to `false`. + +```yaml +cubes: + - name: orders + sql_table: ECOM.ORDERS + public: false +``` + +Let’s create our first Semantic Layer Sync with [Apache Superset](https://superset.apache.org/)! + +You can create a new sync by navigating to the Semantic Layer Sync tab on the BI Integrations page and clicking + Create Sync. +Follow the steps in the wizard to create a sync. + +Under the hood, Semantic Layer Sync is configured using the `semanticLayerSync` option in the `cube.js` configuration file. + +Cube uses the Superset API, which requires a `user` and `password` for authentication. +You can use your own username and password or create a new service account. You can copy a `URL` from any page of your Superset workspace. + +Example `cube.js` configuration file for Superset: + +```yaml +module.exports = { + semanticLayerSync: () => { + return [{ + type: "superset", + name: "Superset Sync", + config: { + user: "mail@example.com", + password: "4dceae-606a03-93ae6dc7", + url: "superset.example.com", + } + }]; + } +}; +``` + +Replace the fields for user, password, and URL with your Superset credentials, then click on Save All. +You can now go to the BI Integrations page and trigger the synchronization of your newly created semantic layer. + +After running the sync, navigate to your Superset instance. You should see the `orders_view` dataset that was created in Superset. +Cube automatically maps all metrics and dimensions in Superset to measures and dimensions in the Cube data model. + +## Manual Setup + +Alternatively, you can connect to Cube and create all the mappings manually. +To do this, navigate to your Apache Superset instance and connect to Cube Cloud as if it were a Postgres database. + +You can find the credentials to connect to Cube on the BI Integrations page under the SQL API Connection tab. + +After connecting, create a new dataset in Superset and select "orders_view" as a table. +Now you can map Superset metrics and columns to Cube's measures and dimensions. + + + +As you can see, we use the `MEASURE` function in the "SQL expression" field. This function informs Cube that we are querying the measure and that it should be evaluated based on Cube's data model. You can now query Cube from Superset, as shown in the image below. + + + +In the next section, we will learn how to use Cube's REST API to query our view from a React app. \ No newline at end of file diff --git a/docs/content/Getting-Started/Cloud/06-Query-from-React.mdx b/docs/content/Getting-Started/Cloud/06-Query-from-React.mdx new file mode 100644 index 0000000000000..63e4c8169161d --- /dev/null +++ b/docs/content/Getting-Started/Cloud/06-Query-from-React.mdx @@ -0,0 +1,77 @@ +--- +title: Query from React app +permalink: /getting-started/cloud/query-from-react-app +category: Getting Started +subCategory: Cube Cloud +menuOrder: 6 +--- + +Cube offers both [REST](/http-api/rest) and [GraphQL](/http-api/graphql) APIs, which can be used to query data from applications built in React or other frontend frameworks. + +You can find your REST API endpoint on the Overview page. In development mode, Cube creates an isolated endpoint for testing data model changes without affecting production. +The structure of your REST API endpoint in development mode should follow the format below. + +```yaml +https://..cubecloudapp.dev/dev-mode//cubejs-api/v1 +``` + +To test your REST API from your terminal, you can use [curl](https://curl.se/). Click on “How to connect your application” next to the REST API, and it will display a code snippet that you can run in your terminal to test the endpoint with curl. + + + +Cube offers a frontend JavaScript SDK, as well as a React integration that you can use in your application. + +First, you’ll need to install two packages from `npm`: + +- [@cubejs-client/core](https://www.npmjs.com/package/@cubejs-client/core) +- [@cubejs-client/react](https://www.npmjs.com/package/@cubejs-client/react) + +Next, initialize `cubejsApi` within your application. + +Please note that you must sign your request with the correct authentication token. Cube uses the [JSON Web Token (JWT)](https://jwt.io/) standard by default to authenticate requests. You can copy a temporary token from the "How to connect to your application" modal window. For production use, you must generate this token from your secret key. You can learn more about this in the [Authentication & Authorization](/security) section of the documentation. + +```jsx +import cubejs from '@cubejs-client/core'; + +const cubejsApi = cubejs( + 'your-token', + { apiUrl: 'https://..cubecloudapp.dev/dev-mode//cubejs-api/v1' } +); +``` + +The Cube React package includes a `CubeProvider` that can be used in your React application. + +```jsx +import { CubeProvider } from '@cubejs-client/react'; + + + // your application + +``` + +Finally, you can use the `useCubeQuery` hook to load data from Cube into your React application. + +```jsx +import { useCubeQuery } from '@cubejs-client/react'; +... +const { resultSet, isLoading, error, progress } = useCubeQuery({ + "measures": ["orders_view.completed_count"], + "timeDimensions": [ + { + "dimension": "orders_view.created_at", + "granularity": "month" + } + ] +}); +``` + +For more information on the Cube JavaScript frontend package and integration with React, please refer to the documentation. + +You can also explore example applications built with React on top of the Cube REST API, along with their source code. + +- [React with Highcharts](https://highcharts-demo.cube.dev/#/) +- [React with AG Grid](https://react-pivot-table-demo.cube.dev/#/) +- [React query builder](https://react-dashboard-demo.cube.dev/#/) \ No newline at end of file