Holistics

https://docs.holistics.io/docs
Admin
Holistics is a modern BI platform that enables self-service data access and exploration for entire...
Tokens:305,341
Snippets:3,356
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Running sync-code from project root

Source: https://docs.holistics.io/docs/cli/sync-code.md

Example of navigating to the repository directory and starting the sync process.

```bash
cd your-holistics-repo
holistics sync-code .
```

--------------------------------

### Product list loop example

Source: https://docs.holistics.io/docs/charts/dynamic-content-blocks/syntax-reference.md

A simple example of displaying product names and revenue using a map loop.

```html

{% map(rows) %}
  
    {{ `Product Name` }} - {{ values.`Revenue` }}
  
{% end %}

```

--------------------------------

### Ecommerce Dataset View Example

Source: https://docs.holistics.io/docs/datasets/custom-views.md

A practical example showing how to organize models and fields for an ecommerce dataset.

```aml
Dataset ecommerce {
  ...

  models: [users, products, orders, dim_dates]
  relationships: [
    relationship(orders.user_id > users.id, true),
    relationship(orders.product_id > products.id, true),
    relationship(orders.order_date > dim_dates.id, true)
  ]
  view {
    model products { }  // Display all fields from Products

    model users {
      // Display selected fields from Users 
      field id
      field email
      field age

    // Create group "Customer Name" containing fields within model Users
    group customer_name {
      field first_name
      field last_name
      field full _name
    }
  }

    // Create group "Order Master" containing two models Orders and Dates 
    group order_master {
      model orders {
        field order_value
        field id
        field order_status
        field order_discount
      }

      model dim_dates {
        field year
        field month name
        field day
        field week_number
        field quarter
      } 
    }
  }
}
```

--------------------------------

### Install autossh and screen

Source: https://docs.holistics.io/docs/connect/connect-tunnel/manual.md

Install the necessary tools for managing persistent SSH tunnels.

```bash
sudo apt-get update
sudo apt-get install autossh
```

```bash
sudo apt-get install screen
```

--------------------------------

### Ecommerce Dataset View Example

Source: https://docs.holistics.io/docs/datasets/custom-views.md

A practical example demonstrating how to import models from multiple modules and organize them within a dataset view using models and groups.

```aml
use sales { orders, products }
use customers { users }

Dataset ecommerce {
  label: 'Ecommerce Dataset'
  data_source_name: 'demodb'

  models: [orders, products, users]

  relationships: [
    relationship(orders.user_id > users.id, true),
    relationship(orders.product_id > products.id, true)
  ]

  view {
    model products { }  // Display all fields from Products

    model users {
      // Display selected fields from Users
      field id
      field email
      field full_name
    }

    // Group models together
    group order_details {
      model orders {
        field id
        field order_value
        field order_status
      }
    }
  }
}
```

--------------------------------

### Install DataHub Holistics connector

Source: https://docs.holistics.io/docs/datahub-integration/setup.md

Install the required Python package via pip.

```bash
pip install datahub-holistics
```

--------------------------------

### Install Holistics Skills

Source: https://docs.holistics.io/docs/development/local-agentic-development.md

Commands to add the marketplace and install the development plugin within Claude Code.

```text
/plugin marketplace add holistics/skills
```

```text
/plugin install holistics-development@holistics-skills
```

--------------------------------

### Set up dbt with BigQuery Adapter

Source: https://docs.holistics.io/docs/continuous-integration/automatic-dbt-integration.md

Installs the dbt BigQuery adapter using pip and runs `dbt deps` to install any necessary packages defined in the dbt project.

```yaml
- name: Set up dbt
  run: |
    pip3 install dbt-bigquery;
    dbt deps;
```

--------------------------------

### Install Holistics CLI on macOS and Linux

Source: https://docs.holistics.io/docs/cli.md

Use this command to download and install the CLI tool. The script supports bash, zsh, and fish shells.

```bash
curl -fsSL https://holistics.io/cli/install | bash
```

--------------------------------

### Authentication Success Output

Source: https://docs.holistics.io/docs/cli.md

Example of the output displayed upon successful authentication.

```text
Logging into https://<secure/us/eu>.holistics.io
Authentication successful. Info:
- ID: 12345
- Email: user@acme.com
- Server URL: https://<secure/us/eu>.holistics.io
```

--------------------------------

### Retention heatmap complete example

Source: https://docs.holistics.io/docs/charts/dynamic-content-blocks/syntax-reference.md

A complete example demonstrating a retention heatmap structure using nested maps.

```html

  
    
      Cohort
      {% map(columns) %}
        {{ `Month Number` }}
      {% end %}
    
  
  
  {% map(rows) %}
  
    {{ `Cohort Month` }}
    {% map(values) %}
      
        {{ value.`Total Users` }}
      
    {% end %}
  
  {% end %}
  

```

--------------------------------

### Install Holistics CLI

Source: https://docs.holistics.io/docs/continuous-integration/automatic-dbt-integration.md

Downloads and installs the Holistics CLI using a curl command and adds its binary directory to the GitHub Actions PATH for subsequent use.

```yaml
- name: Install Holistics CLI
  run: |
    curl -fsSL https://raw.githubusercontent.com/holistics/holistics-cli/refs/heads/master/install.sh | bash
    echo "$HOME/.holistics/bin" >> $GITHUB_PATH
```

--------------------------------

### Valid AML object names

Source: https://docs.holistics.io/docs/development/aml-studio.md

Examples of valid object names. These must not start with numbers or special characters (except underscores) and cannot contain spaces.

```text
order_master
OrderMaster
_order_master
business_metrics
```

--------------------------------

### Project folder structure example

Source: https://docs.holistics.io/docs/development/aml-studio.md

Demonstrates organizing models and datasets into folders. Object names must remain unique across the entire project.

```text
data_warehouse
    ├── region_asia
    │   ├── orders.model.aml                // contains model orders_asia
    │   ├── products.model.aml              // contains model products_asia
    │   └── business_metrics.dataset.aml    // contains dataset business_metrics_asia
    |
    └── region_europe
        ├── orders.model.aml                // contains model orders_europe
        ├── products.model.aml              // contains model products_europe
        └── business_metrics.dataset.aml    // contains dataset business_metrics_europe
```

--------------------------------

### Microsoft Forms Integration

Source: https://docs.holistics.io/docs/access-control/custom-access-request-page.md

An HTML example for integrating with Microsoft Forms, suitable for Office 365 users. This setup allows for creating access request forms.

```html
<!-- For Office 365 users -->

  Request via Microsoft Forms  

```

--------------------------------

### Initialize AMQL Development

Source: https://docs.holistics.io/docs/development/local-agentic-development.md

Command to trigger the setup skill for configuring the CLI, MCP server, and sync session.

```text
/setup-amql-development
```

--------------------------------

### Syntax Error Example

Source: https://docs.holistics.io/docs/continuous-integration/auto-publish.md

This JSON response indicates a syntax error in the project. The 'error_details' field specifies the file path, start and end offsets, and the error message.

```json
{
  "status": "success", // job status
  "error": null,
  "result": {
    // result of the publishing process
    "type": "Publish",
    "data": {
      "status": "error", // publish status
      "error_type": "syntax_error",
      "error_details": {
        "diagnostics": [
          {
            "category": "Error",
            "code": 1000,
            "message": "Unexpected ';'",
            "filePath": "/ecommerce_dashboard.page.aml", // file path contain the error
            "start": 1469, // offset of the error in the code
            "end": 1470 // offset of the error in the code
          }
        ]
      },
      "target_commit": "0bf1e7421b78eea7d9ce4ac9d07db9584e5c5d76"
    }
  }
}
```

--------------------------------

### Start local preview sync

Source: https://docs.holistics.io/docs/connect/databases/databricks-metric-views.md

Synchronize the local project with the Holistics environment to preview changes in Reporting and Canvas Dashboards.

```bash
holistics sync-code .
```

--------------------------------

### Create a Top Product Card Template

Source: https://docs.holistics.io/docs/charts/dynamic-content-blocks/getting-started.md

Build a styled card to display the top product and its revenue. This example uses HTML for structure and styling, with template syntax to inject dynamic data.

```html
<style>
  .product-card {
    padding: 1.5rem;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border-radius: 12px;
    color: white;
    max-width: 300px;
  }
  .product-card h3 {
    margin: 0 0 0.5rem 0;
    font-size: 1.25rem;
  }
  .product-card .revenue {
    font-size: 1rem;
    color: lightgreen
  }
  .product-card .title {
    font-size: 0.875rem;
    opacity: 0.8;
  }
</style>

  Top Product
  {{ rows[0].`Product Name` }}
  {{ rows[0].values.`Revenue` }}
```

--------------------------------

### Verify Holistics CLI Installation

Source: https://docs.holistics.io/docs/datahub-integration/setup.md

Check if the Holistics CLI is correctly installed and accessible in the system PATH.

```bash
holistics --version
```

--------------------------------

### Create and Configure SFTP Directories

Source: https://docs.holistics.io/docs/delivery/sftp-schedules.md

Sets up the necessary directories for SFTP access. The parent directory `/holistics` is owned by root for Chroot configuration, while the inner `exported` directory is owned by the SFTP user for file storage.

```bash
mkdir -p /holistics
chown root: /holistics
```

```bash
mkdir -p /holistics/exported
chown holistics_sftp: /holistics/exported
chmod 0755 /holistics/exported
```

--------------------------------

### Basic usage of sync-code

Source: https://docs.holistics.io/docs/cli/sync-code.md

Run this command to initiate continuous synchronization of the specified project path.

```bash
holistics sync-code <repo-path>
```

--------------------------------

### Install Holistics AML extension via CLI

Source: https://docs.holistics.io/docs/development/vscode-extension.md

Use the command line to install the official Holistics AML extension for VS Code.

```bash
code --install-extension holistics.holistics-aml-vscode-ext
```

--------------------------------

### Set up Python Environment

Source: https://docs.holistics.io/docs/continuous-integration/automatic-dbt-integration.md

Configures the GitHub Actions runner to use a specific Python version (3.7 in this case) using the actions/setup-python@v4 action.

```yaml
- name: Set up Python
  uses: actions/setup-python@v4
  with:
    python-version: 3.7
```

--------------------------------

### Clone and Prepare Repository

Source: https://docs.holistics.io/docs/development/local-agentic-development.md

Commands to clone a Holistics repository and create a new feature branch for development.

```bash
git clone git@github.com:your-org/your-holistics-repository.git
cd your-holistics-repository
git checkout -b feature/add-new-dashboard
```

--------------------------------

### Compare Default Filtering vs Query Parameters

Source: https://docs.holistics.io/docs/query-models.md

Demonstrates the difference between applying filters on the result set versus injecting them directly into the SQL query using the {% filter %} syntax.

```sql
# 'order_aggregated' model
select
  order_date,
  count(*) as order_count
from orders

group by 1

# Apply "Order Date = '2024-01-01'" filter from dashboard
with order_aggregated as (
  select
    order_date,
    count(*) as order_count
  from orders

  group by 1  
)

select
  order_date,
  order_count
from order_aggregated
where order_date = '2024-01-01'  # Filter outside of CTE
```

```sql
# 'order_aggregated' model
select
  order_date,
  count(*) as order_count
from orders
where {% filter(order_date_param) %} orders.order_date {% end %}
group by 1

# Apply "Order Date = '2024-01-01'" filter from dashboard
with order_aggregated as (
  select
    order_date,
    count(*) as order_count
  from orders
  where order_date = '2024-01-01'  # Filter inside of CTE
  group by 1  
)

select
  order_date,
  order_count
from order_aggregated
```

--------------------------------

### System Prompt Configuration

Source: https://docs.holistics.io/docs/ai/mcp-server/slack.md

Define the bot's behavior and instructions for interacting with the Holistics MCP tool in prompt.txt.

```markdown
# Holistics
You have access to the Holistics MCP (Model Context Protocol) tool, which provides powerful data analytics and business intelligence capabilities. Here's how to use it effectively:
## When to Use Holistics MCP:
- When users ask about business metrics, KPIs, or data analytics.
- When users need specific numbers, trends, or insights from company data.
- When users request insight information or detailed data.
- When users want to explore available datasets or understand data relationships.
## Best Practices:
1. **Be Specific**: When querying data, be as specific as possible with date ranges, filters, and dimensions.
2. **Handle Errors Gracefully**: If the MCP tool returns an error, display the original error message, explain what might have gone wrong and suggest alternatives.
3. ALWAYS check the actual dataset names using list_datasets tool.
4. Combine answers from multiple datasets if one is not enough.
## Response Format:
When using the Holistics MCP tool:
- ALWAYS include the dataset name (wrapped inside `) in your response.
- Clearly state what data you're retrieving.
- Present results in a clear, formatted manner.
- Include relevant context about the time period, filters applied, and which specific datasets were used.
- If it makes sense, you can provide an inline markdown table (inside a markdown quoted block, suitable for Slack formatting) to visualize the result.
- If the result has any links, include them in your response.
```

--------------------------------

### Example of Filter Order: Date and Top N

Source: https://docs.holistics.io/docs/top-bottom-n-filter.md

Demonstrates how a date filter is applied before a Top N filter, resulting in a different set of top products.

```text
Sony Smart TV, Body Cleanser and Sofa 1
```

--------------------------------

### Date-drill Filter Examples

Source: https://docs.holistics.io/docs/url-parameters.md

Use the '=' operator for date-drill filters. The parameter is case-insensitive.

```url
url?date_drill=Month
```

```url
url?date_drill=year
```

--------------------------------

### Define Model Build Behaviors

Source: https://docs.holistics.io/docs/persistence.md

Example configuration showing mixed rebuild and reuse strategies across a model dependency tree.

```aml
Model model_a {
  type: 'query'

  persistence: FullPersistence {
    schema: 'persisted'
    // highlight-next-line
    on_cascade: 'rebuild'
  }
}

Model model_b {
  type: 'query'
  models: [model_a]

  persistence: FullPersistence {
    schema: 'persisted'
    // highlight-next-line
    on_cascade: 'reuse'
  }
}

Model model_c {
  type: 'query'
  models: [model_a]
  
  persistence: FullPersistence {
    schema: 'persisted'
    // highlight-next-line
    on_cascade: 'rebuild'
  }
}

Model model_d {
  type: 'query'
  models: [model_b, model_c]

  persistence: FullPersistence {
    schema: 'persisted'
    // highlight-next-line
    on_cascade: 'rebuild'
  }
}
```

--------------------------------

### Define source tables in DBML

Source: https://docs.holistics.io/docs/modeling/modeling-patterns/denormalized-rollup-tables.md

Schema definition for the normalized source tables used in the examples.

```dbml
Table tickets {
  id integer [pk]
  agent_id integer
  customer_id integer
  created_at datetime
}

Table agents {
  id integer [pk]
  name varchar
}

Table customers {
  id integer [pk]
  tier varchar
}
```

--------------------------------

### Implement Parameter References in VizBlock

Source: https://docs.holistics.io/docs/canvas-dashboard/guides/build-library-blocks.md

Demonstrates how to use defined parameters within a VizBlock using string interpolation for AQL field definitions.

```aml
Func mrr_breakdown(
  dataset: Dataset = saas_dataset,
  mrr_amount: VizFieldRef = r(mrr_transactions.mrr_amount),
  break_down_dimension: VizFieldRef = r(mrr_transactions.subscription_type),
  date: VizFieldRef = r(mrr_transactions.subscription_type),
  comparison_period: Number = 12
) {
    VizBlock {
        viz: CombinationChart {
            // Use dataset parameter
            //highlight-next-line
            dataset: dataset,
            calculation metric {
                // Use mrr_amount parameter in field formula with string interpolation
                //highlight-next-line
                formula: @aql sum(${mrr_amount.model}.${mrr_amount.field}),
            }
            legend: VizFieldFull {
                // Use break_down_dimension parameter
                //highlight-next-line
                ref: break_down_dimension
                format {
                    type: 'text'
                }
            }
            filter {
                // Use other parameters
                //highlight-next-line
                field: date
                operator: 'last'
                //highlight-next-line
                value: comparison_period
                modifier: 'month'
            }
        }
    }
}
```

--------------------------------

### Define Dataset Relationships

Source: https://docs.holistics.io/docs/joins/path-ambiguity.md

Example configuration of an e-commerce dataset with multiple models and defined relationships.

```aml
Dataset ecommerce {
  ...
  models: [orders, users, order_items, countries, merchants, products, cities]

  relationships: [
    relationship(orders.user_id > users.id, true),
    relationship(order_items.order_id > orders.id, true),
    relationship(cities.country_code > countries.code, true),
    relationship(users.city_id > cities.id, true),
    relationship(order_items.product_id > products.id, true),
    relationship(products.merchant_id > merchants.id, true),
    relationship(merchants.city_id > cities.id, true)
  ]
}
```

--------------------------------

### Invalid Group of Groups Structure

Source: https://docs.holistics.io/docs/datasets/custom-views.md

An example of an invalid structure where a group contains another group.

```text
Dataset
└── view
    └── group
        └── group
```

--------------------------------

### Alphabetical Month Name Ordering

Source: https://docs.holistics.io/docs/charts/cohort-retention.md

Example of month names that result in incorrect alphabetical sorting.

```text
'Jan 2019', 'Feb 2019', 'Mar 2019', 'Apr 2019'...
```

--------------------------------

### Define AQL measure in Model

Source: https://docs.holistics.io/docs/aggregate-awareness/faqs.md

Example of a basic AQL measure definition within a model.

```aml
Model transactions {
  measure count_transactions {
    type: 'number'
    definition: @aql count(transactions.id);;
  }
}
```

--------------------------------

### Define a Canvas Dashboard

Source: https://docs.holistics.io/docs/canvas-dashboard/reusable-components.md

Initial setup of a dashboard containing text, filter, and visualization blocks.

```tsx
Dashboard my_dashboard {
  // metadata
  title: 'My Canvas Dashboard'
  description: 'My new Canvas Dashboard'

  // collection of blocks
  block t1: TextBlock {
    content: @md
      Hello world
    ;;
  }

  block f1: FilterBlock {
    type: 'field'
    label: 'User role'
    source: FieldFilterSource {
      dataset: 'tenant_user'
      field: r(public_users.role)
    }
  }

  block v1: VizBlock {
    label: 'A pie chart'
    viz: PieChart {
      dataset: 'tenant_user'
      legend: r(public_users.role)
      series {
        field {
          ref: r(public_users.id)
          aggregation: 'sum'
        }
      }
    }
  }

  // layout
  view: CanvasLayout {
    width: 1200
    height: 1200
    margin: 10
    block f1 {
      position: pos(600, 0, 300, 70)
    }
    block v1 {
      position: pos(0, 70, 600, 600)
    }
  }
}
```

--------------------------------

### SQL Queries for Metric Sheet Aggregation

Source: https://docs.holistics.io/docs/charts/metric-sheets.md

SQL examples showing how Metric Sheets recalculate metrics based on the selected aggregation period.

```sql
select
	D.date_d
  , COUNT(DISTINCT user_id) AS active_users
from activities A ON D.date_d = A.date_d
```

```sql
select
  DATE_TRUNC('week', D.date_d) as week_d -- aggregation period is changed
  , COUNT(DISTINCT user_id) AS active_users
from dim_dates D
left join activities A ON D.date_d = A.date_d
```

--------------------------------

### Organize dataset files

Source: https://docs.holistics.io/docs/from-others/looker/model-migration.md

Recommended file structure for Holistics datasets.

```text
📁 datasets/
  📄 orders.dataset.aml
  📄 products.dataset.aml
  📄 users.dataset.aml
```

--------------------------------

### Number Filter Example

Source: https://docs.holistics.io/docs/url-parameters.md

Use the '=' operator for number filters. Both integer and float values are supported.

```url
url?score=8
```

```url
url?score=8.0
```

--------------------------------

### Recommended SQL to AQL conversion

Source: https://docs.holistics.io/docs/aggregate-awareness/faqs.md

Best practice for defining measures using AQL syntax for optimal metric awareness.

```aml
// in Model definition
measure sum_x {
  label: 'Sum of X'
  type: 'number'
  definition: @aql sum(model.x);;
}

// in PreAggregate definition
measure sum_x {
  for: r(model.x)
  aggregation_type: 'sum'
}
```
Tokens:
Raw