# Connect to Cube

Arcwise connects to the [Cube SQL API](https://cube.dev/docs/product/apis-integrations/sql-api) and allows end-users to query public views (and metrics within views).

## Setting up the Cube connection

1. In the Arcwise admin panel, [create a new connection](https://admin.arcwise.app/#/warehouse_connections/create) and select Cube.dev as the warehouse type.
2. The "Name" can be anything you want (preferably something user-friendly.)
3. Enter your Cube credentials below (can either be a Cube Cloud or self-hosted deployment). Information for an example Cube Cloud instance can be seen below.

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2FX68W1iVjiTANv1vgR2u9%2FCleanShot%202024-05-31%20at%2010.25.10%402x.png?alt=media&#x26;token=d5a16231-60af-42ee-829b-5db2a3db69d9" alt="" width="375"><figcaption></figcaption></figure>

4. If everything is successful, the[ "Tables" tab](https://admin.arcwise.app/#/warehouse_entities) should display a list of your Cube views. (We also pull out each _measure_ associated with a view so that users can query them through formulas, as shown below).

{% hint style="info" %}
Support for [security contexts](https://cube.dev/docs/product/auth/context), particularly at the user level, is still under development.
{% endhint %}

#### (Optional) Configuring the AI Analyst

If you want to make best use of the AI Analyst, head to the [AI tab](https://admin.arcwise.app/#/ai) in the Arcwise admin panel to configure some settings:

1. By default, the AI will only query tables that have been explicitly connected to a spreadsheet. You can add patterns in the "Table patterns to auto-include in AI conversations" setting to configure tables/views that should be automatically available to the AI.
2. The "Table metadata" section can be used to add additional context/descriptions at the view & column level to the AI.
3. The "Additional system prompt" can be used to add global context to each AI conversation.

## Using cubes in Arcwise

Arcwise offers three primary ways to work with data from Cube.

### Pivoting a Cube view

Open the Arcwise extension in Google Sheets and click "Connect Data" to open a browser of all connected data sources. You should be able to find your Cube views by searching the "Database" tab:

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2FjPjZD9c24JZKxil5DG3m%2FCleanShot%202024-05-31%20at%2010.33.49%402x.png?alt=media&#x26;token=62bd840f-d298-493b-9e2e-9add9fdbfff3" alt="" width="563"><figcaption></figcaption></figure>

After clicking on your view, the right pane displays a list of public dimensions and measures.

{% hint style="info" %}
The preview and connect buttons will directly pull the (ungrouped) data in the view. This usually isn't what you want to do.
{% endhint %}

Clicking the "Pivot" button will pull up a pivot table UI where you can freely move dimensions to rows/columns and measures (green) to values:

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2FFAPJoyimoe6uqQRz2nso%2FCleanShot%202024-05-31%20at%2010.37.33%402x.png?alt=media&#x26;token=4fb859c8-aa09-405e-b209-c74ff9cfb4c1" alt=""><figcaption><p>A basic pivot table on an orders cube, showing Order Count by Product Category vs. Status.</p></figcaption></figure>

Clicking "Connect" will save the pivot table into the spreadsheet.

Users can also change the "Chart type" at the top right to easily visualize the data in the pivot table as a bar, line, scatter, area, or pie chart:

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2FLDq7C2BVJ2xu7vIVrBTw%2FCleanShot%202024-05-31%20at%2010.39.01%402x.png?alt=media&#x26;token=0694d487-d8ca-470b-8d30-cd3045d7ef9b" alt=""><figcaption><p>Bar chart view of the pivot table.</p></figcaption></figure>

Clicking "Save" will save the visualization into the spreadsheet; users can bring up the visualization editor again by simply double-clicking on the saved visualizations.

#### Editing a saved pivot table

Once saved in the sheet, there are a few features to call out:

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2FA8Qdh5Uj6DnfossCqN8l%2FCleanShot%202024-05-31%20at%2010.40.54%402x.png?alt=media&#x26;token=b473de6b-c4f0-4790-b94e-34f8f87b47df" alt=""><figcaption><p>Saved Cube pivot in a Google Sheet</p></figcaption></figure>

First, the inline overlay within the sheet tab displays a few key actions (from left-to-right: "Edit", "Analyze", "Refresh", "Drilldown".)

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2F0Oz33ouc3P9X73mpjLTN%2FCleanShot%202024-05-31%20at%2010.46.50%402x.png?alt=media&#x26;token=d7c9f020-c034-49d3-b033-84339c8f3697" alt="" width="163"><figcaption></figcaption></figure>

* **Edit**: Brings up the overlay on the right, which allows the pivot fields to be edited. You can also add new "table calculation" formulas under the "Additional fields" section at the bottom.
  * (In the screenshot, "completion\_rate" is defined as a table calculation formula: `completed_count / order_count`)
  * See more here: [arcwise-connected-data](../../using-arcwise-in-sheets/arcwise-connected-data "mention")
* **Analyze**: Opens up the AI Analyst, focused on the current pivot. See more at [using-ai-analyst-in-sheets](../../using-arcwise-ai-analyst/using-ai-analyst-in-sheets "mention")
* **Refresh:** Re-runs the query and updates the contents of the current spreadsheet tab.
* **Drilldown:** If the selected spreadsheet cell is a pivot **value**, the drilldown view shows the ungrouped rows in the cube that match the filters defined by the rows and columns.

### Running metric formulas

In any spreadsheet cell, typing `=$` will show a list of public **measures** exposed by any Cube view:

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2FbOMI1r36Wh4RHdL0yGlQ%2FCleanShot%202024-05-31%20at%2010.52.38%402x.png?alt=media&#x26;token=f7456397-fe10-48be-baef-5b9f4163d2d7" alt="" width="375"><figcaption><p>Metric formula autocompletion</p></figcaption></figure>

Here is an example of a complete formula that queries the **Order Count** measure where the **status** dimension is equal to A1 and the **created\_at** column is after B1:

```
=$orders_cube.order_count("status", $A1, "created_at", ">"&B$1)
```

* Each measure is available as a spreadsheet function `$view_name.measure_name`.
* If no parameters are provided, the measure is queried over all rows (usually not desirable.)
* Otherwise, parameters should come in pairs:
  * The 1st, 3rd, 5th, ... parameters should be the string **dimension name** associated with the measure's view. (A list of suitable dimensions will be displayed in the autocompletion menu.)
  * The 2nd, 4th, 6th, ... parameters will be used as the comparison value for the immediately preceding dimension.
    * If the comparison is a string, COUNTIF/SUMIF criteria syntax is supported, i.e. you can pass in `"<X", ">X", "<=X", "<>X"` to compare the specified dimension against a certian value.
    * You can even pass in **ranges** as the comparison value (e.g. `A1:A10`) for the result of the metric formula to be an **array** of values. (Careful that in Google Sheets, you'll need to use the [`ARRAYFORMULA` function](https://support.google.com/docs/answer/3093275?hl=en) if you want to chain computations on top of the function result, e.g. `=ARRAYFORMULA($orders_cube.order_count(...) + 1)`

**IMPORTANT**: Arcwise formulas (including measure formulas) deviate from normal spreadsheet formulas in that their values **do not update automatically, even when dependencies change.** This is to protect against cascading updates overwhelming your database, and to make sure that cell values do not dynamically change without explicit user interactions.

See [formulas](../../using-arcwise-in-sheets/formulas "mention") for an overview of how to refresh Arcwise formulas.

### Using the AI analyst

See [using-ai-analyst-in-sheets](../../using-arcwise-ai-analyst/using-ai-analyst-in-sheets "mention") for more details. The Arcwise AI analyst knows how to automatically generate **pivot tables** for Cube data (and visualizations based off those pivot tables) - you'll generally want to make sure that your Cube views are auto-included (see [#optional-configuring-the-ai-analyst](#optional-configuring-the-ai-analyst "mention") above.)

<figure><img src="https://803372693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlIfwCAQgoIa97JJYtlXQ%2Fuploads%2Fd3ppW1qtskxHqktEvS7E%2FCleanShot%202024-05-31%20at%2011.11.19%402x.png?alt=media&#x26;token=23182e03-57f2-4294-9c27-266d0eeafc63" alt="" width="375"><figcaption></figcaption></figure>
