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:

cubes:
  - name: users
    # ...

    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

cube(`users`, {
  // ...
  segments: {
    sf_users: {
      sql: `${CUBE}.location = 'San Francisco'`
    }
  }
})

Or use segments to implement cross-column OR logic:

cubes:
  - name: users
    # ...

    segments:
      - name: sf_users
        sql: |
          {CUBE}.location = 'San Francisco' OR {CUBE}.state = 'CA'

cube(`users`, {
  // ...

  segments: {
    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.

cubes:
  - name: users
    # ...

    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

cube(`users`, {
  // ...

  segments: {
    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.

cubes:
  - name: users
    # ...

    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"
        description: Users from San Francisco

cube(`users`, {
  // ...

  segments: {
    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.

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

cube(`users`, {
  segments: {
    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.

cubes:
  - name: users
    # ...

    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

cube(`users`, {
  // ...

  segments: {
    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:

cubes:
  - name: users
    # ...

    dimensions:
      - name: location
        sql: location
        type: string

    segments:
      - name: sf_users
        sql: "{CUBE}.location = 'San Francisco'"

cube(`users`, {
  // ...

  dimensions: {
    location: {
      sql: `location`,
      type: `string`
    }
  },

  segments: {
    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:

cubes:
  - name: users
    # ...

    segments:
      - name: sf_ny_users
        sql: |
          {CUBE}.location = 'San Francisco' OR {CUBE}.location like '%New York%'

cube(`users`, {
  // ...

  segments: {
    sf_ny_users: {
      sql: `
        ${CUBE}.location = 'San Francisco' OR
        ${CUBE}.location like '%New York%'
      `
    }
  }
})

Data Modeling

Configuration

Core Data APIs

Embed APIs

Other APIs

JavaScript SDK

Parameters

`name`

`description`

`public`

`sql`

Segments vs Dimension Filters

​Parameters

​name

​description

​public

​sql

​Segments vs Dimension Filters

Parameters

`name`

`description`

`public`

`sql`

Segments vs Dimension Filters