Documentation
Data modeling
Reference
Segments

Segments

You can use the segments parameter within cubes to define segments. Segments are predefined filters. You can use segments to define complex filtering logic in SQL.

For example, users for one particular city can be treated as a segment:

YAML
JavaScript
cubes:
  - name: users
    # ...
 
    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

Or use segments to implement cross-column OR logic:

YAML
JavaScript
cubes:
  - name: users
    # ...
 
    segments:
      - name: sf_users
        sql: |
          {CUBE}.location = 'San Francisco' OR {CUBE}.state = 'CA'

As with other cube member definitions, segments can be generated:

const userSegments = {
  sf_users: ["San Francisco", "CA"],
  ny_users: ["New York City", "NY"]
}
 
cube(`users`, {
  // ...
 
  segments: {
    ...Object.keys(userSegments)
      .map((segment) => ({
        [segment]: {
          sql: `${CUBE}.location = '${userSegments[segment][0]}' or ${CUBE}.state = '${userSegments[segment][1]}'`
        }
      }))
      .reduce((a, b) => ({ ...a, ...b }))
  }
})

After defining a segment, you can pass it in query object:

{
  "measures": ["users.count"],
  "segments": ["users.sf_users"]
}

Parameters

name

The name parameter serves as the identifier of a segment. It must be unique among all segments, dimensions, and measures within a cube and follow the naming conventions.

YAML
JavaScript
cubes:
  - name: users
    # ...
 
    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

description

This parameter provides a human-readable description of a segment. When applicable, it will be displayed in Playground and exposed to data consumers via APIs and integrations.

YAML
JavaScript
cubes:
  - name: users
    # ...
 
    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"
        description: Users from San Francisco

public

The public parameter is used to manage the visibility of a segment. Valid values for public are true and false. When set to false, this segment cannot be queried through the API. Defaults to true.

YAML
JavaScript
cubes:
  - name: users
    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"
        public: false

sql

The sql parameter defines how a segment would filter out a subset of data. It takes any SQL expression that would be valid within a WHERE statement.

YAML
JavaScript
cubes:
  - name: users
    # ...
 
    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

Segments vs Dimension Filters

As segments are simply predefined filters, it can be difficult to determine when to use segments instead of filters on dimensions.

Let's consider an example:

YAML
JavaScript
cubes:
  - name: users
    # ...
 
    dimensions:
      - name: location
        sql: location
        type: string
 
    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

In this case following queries are equivalent:

{
  "measures": ["users.count"],
  "filters": [
    {
      "member": "users.location",
      "operator": "equals",
      "values": ["San Francisco"]
    }
  ]
}

and

{
  "measures": ["users.count"],
  "segments": ["users.sf_users"]
}

This case is a bad candidate for segment usage and a filter on a dimension works better here. users.location filter value can change a lot for user queries and users.sf_users segment won't be used much in this case.

A good candidate case for a segment is when you have a complex filtering expression which can be reused for a lot of user queries. For example:

YAML
JavaScript
cubes:
  - name: users
    # ...
 
    segments:
      - name: sf_ny_users
        sql: |
          {CUBE}.location = 'San Francisco' OR {CUBE}.location like '%New York%'
HierarchiesJoins