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:

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

Or use segments to implement cross-column OR logic:

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.

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.

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.

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.

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:

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:

cube(`users`, {
  // ...
 
  segments: {
    sf_ny_users: {
      sql: `
        ${CUBE}.location = 'San Francisco' OR
        ${CUBE}.location like '%New York%'
      `,
    },
  },
});