Help Center

Menu

Segments

Defining a segment

A segment is defined and named in the blueprint. Segment names are case-sensitive, and both upper- and lower-case names are valid.

Create a segment called at-risk, which filters students with a GPA of less than two in the Comp-255 course:

...
paths:
  /students:
    ...

x-datastore-segments:
  at-risk: # unique segment name
    collections: '/students'
    definition:
      - property: 'document.gpa'
        comparison: '<'
        value: 2
      - property: 'document.course'
        comparison: '==='
        value: 'comp-255'

The equivalent query string would look like this:

?filters=document.gpa<2;document.course===comp-255

Specifying segments on the query string

Segments are specified using the following syntax:

?segment=SEGMENT_NAME

Reference the at-risk segment with the string:

?segment=at-risk

Sorting segments

You can specify the sort order to return the data in the segment.

You can specify additional sorting in the application. These override the default sort defined in the segment.

Sort the at-risk segment by the studentid and then the year.

...
paths:
  /students:
    ...

x-datastore-segments:
  at-risk:
    collections: '/students'
    sort: # Optional default to document id
      - direction: 'asc'
        property: 'document.studentid'
      - direction: 'desc'
        property: 'document.year'
    ...

The equivalent query string would be:

?sort=document.studentid,-document.year

Aggregating segments

Segments can have aggregation rules specified as part of the configuration. You cannot add additional aggregation specifications outside of the segment configuration.

Aggregate the at-risk segment with this configuration:

...
paths:
  /students:
    ...

x-datastore-segments:
  at-risk:
    collections: /students
    aggregation:
      count:
        group:
          - document.year
        property: document.gpa
    ...

The equivalent query string would be:

?agg[func]=count&agg[group]=document.year&agg[prop]=document.gpa

Using result limits

Segments can have an optional limit specified as part of the configuration.

A segment with a result limit set only returns as many results as specified in the limit, even if a higher number of results are available. Frontend apps cannot paginate past this limit.

If the number of results is lower than the limit, all results are returned.

Use the following configuration to return only the top 100 students in the at-risk segment:

...
paths:
  /students:
    ...

x-datastore-segments:
  at-risk:
    collections: /students
    limit: 100
    ...

Applying additional filters to segments

You can apply additional filters to segments at runtime. Additional filters on a segment are applied to the segmented data instead of the whole collection.

Applying segments to multiple collections

You can apply a segment to a collection or an alias. The segment is automatically applied to all alias paths if the collection has any aliases.

Targeting Javascript SDK with segments

Segments can be targeted with the JavaScript SDK.

Example 1. Student blueprint
datastore.collection('students').segment('at-risk').get();

datastore.collection('students').segment('at-risk').where('gender', '===', 'male').get();

datastore.collection('students').segment('at-risk').limit(10).get();

datastore.collection('students').segment('at-risk').sortBy('gpa', 'asc').get();